Connecting Syndesis to Applications and Services
To integrate applications, you create a connection to each application or service that you want to integrate. You then create an integration and add a connection to it for each integration or service that you want to integrate.
Syndesis supports numerous connectors that serve as templates for creating connections. The following topics provide details for creating connections and adding them to integrations:
Connectors that are supported by Syndesis
Syndesis supports the following connectors.
| Name | Description |
|---|---|
Obtain, add, update, or delete data in an Amazon DynamoDB table. |
|
Send messages to an Amazon SNS topic. |
|
Retrieve messages from or send messages to an Amazon SQS queue. |
|
Retrieve data from an Amazon S3 bucket or copy data into a bucket. |
|
Obtain messages from a Red Hat AMQ (Apache ActiveMQ) broker or publish messages to a Red Hat AMQ (Apache ActiveMQ) broker. |
|
Obtain messages from an Advanced Message Queue Protocol broker or publish messages to an AMQP broker. |
|
Download files from Box or upload files to Box. |
|
Download files from Dropbox or upload files to Dropbox. |
|
Retrieve email from an IMAP or POP3 email server or connect to an SMTP email server to send email. |
|
Obtain resources from a FHIR server or update resources on a FHIR server. |
|
Download files from an FTP or SFTP server or upload files to an FTP or SFTP server. |
|
Obtain messages sent to a particular Gmail account and send messages from a particular Gmail account. |
|
Obtain events from a Google Calendar that you specify or add/update events in a Google Calendar that you specify. |
|
Obtain data from a Google Sheets spreadsheet that you specify, add/update spreadsheet data, create charts, or create pivot tables in a spreadsheet that you specify. |
|
Connect to an HTTP or HTTPS endpoint and execute the
|
|
Receive messages that are sent to an IRC nickname or channel, or send messages to an IRC nickname on a particular channel. |
|
Obtain, create, or update issues on a Jira server. |
|
Obtain messages from a Knative channel, send messages to a Knative channel, expose a simple integration as a Knative service, or call a Knative service. |
|
Obtain records from a table in an Apache Kudu data store or add records to a table in a Kudu data store. |
|
Obtain data from a MongoDB database or update data in a MongoDB database. |
|
Obtain messages from an MQ Telemetry Transport broker or publish messages to an MQTT broker. |
|
Obtain entities from an OData service or update, create, or delete entities that are managed by an OData service. |
|
Create a custom REST API client connector by uploading an OpenAPI document. You can then create a connection to that REST API. Create a REST API provider integration by uploading an OpenAPI document that defines operations that trigger integration execution. See Creating an integration that is triggered by a REST API call in Integrating Applications. |
|
Create, update, fetch, or delete a Salesforce record. |
|
Perform any one of a large variety of SAP Concur actions. |
|
Obtain records from or copy records to your ServiceNow instance. |
|
Obtain messages from a channel or send a message to a Slack channel or user. |
|
Invoke a SQL statement or a SQL stored procedure on an Apache Derby, MySQL, or PostgreSQL database. To connect to other types of SQL databases, you upload a Syndesis library extension that contains a JDBC driver for that database. |
|
Obtain messages from a chat or send messages to a chat by using a Telegram chat bot. |
|
Trigger execution of a simple integration upon tweets that mention you or that contain data that you specify. |
|
Trigger execution of simple integrations with HTTP |
If Syndesis does not provide a connector that you need, an
experienced developer can create an extension that defines a custom
connector. For information about coding the
extension and creating its .jar
file, which you upload to
Syndesis, see:
Connecting to Amazon Web Services
A Syndesis integration can connect to the following Amazon web services:
-
DynamoDB
-
Simple Notification Service (SNS)
-
Simple Queue Service (SQS)
-
Simple Storage Service (S3)
You must obtain AWS credentials before you can create a connection to an Amazon web service. For details, see:
Obtaining AWS credentials for creating connections to Amazon services
To create a connection to an Amazon service, you must have an access key that is associated with an AWS account. This is the AWS account that created, or will create, the resource that you want the Syndesis connection to access. The resource can be an S3 bucket, an SNS topic, or an SQS queue.
An AWS access key has two parts:
-
Amazon access key ID
-
Amazon secret access key
AWS uses access keys to authenticate requests from a Syndesis connection. There is plenty of AWS documentation about creating and managing access keys. If you already created an AWS Identity and Access Management (IAM) user and captured the access key associated with that user, you can specify those values to create a Syndesis connection to S3, SNS, or SQS.
If you need to obtain an access key, the procedure below is one way to do it.
-
Login credentials for the AWS account that created the resource that you want a connection to access.
-
Or, login credentials for the AWS account that you want the connection to use to create a new resource.
-
Go to https://aws.amazon.com/ and sign in to the console.
-
In the console, in the upper right, click the down arrow next to the user name and click My Security Credentials.
-
In the popup dialog, click Get Started with IAM Users.
If a popup with this button does not appear, then on the left, click Users.
-
Add a user:
-
Click Add User
-
Enter a user name and select Programmatic Access.
-
Click Next: Permissions.
-
Respond to the prompts for adding the new user to a group.
-
Click Next: Tags.
-
Skip adding tags and click Next: Review.
-
Click Create User.
-
-
Click Download .csv to obtain a local copy of the access key. The downloaded file contains the access key ID and the secret access key, which you must specify to create a connection to an Amazon service.
-
Click Close.
Connecting to Amazon DynamoDB
An integration can retrieve data from an Amazon DynamoDB table, add data to a DynamoDB table, or remove data from a DynamoDB table. To do this, create an Amazon DynamoDB connection and then add that connection to an integration flow.
For details, see:
Creating Amazon DynamoDB connections
You must create an Amazon DynamoDB connection before you can connect to Amazon DynamoDB in an integration.
-
You must have an AWS access key. See Obtaining AWS credentials for creating connections to Amazon services.
-
You must know which AWS region contains the DynamoDB table that you want the connection to access.
-
You must know the name of the DynamoDB table that you want the connection to access. This table must exist when an integration connects to DynamoDB.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Amazon DynamoDB connector.
-
In the Access Key field, enter an Amazon access key ID that is part of a user access key in the AWS account that manages the DynamoDB table that you want the connection to access.
-
In the Secret Key field, enter the Amazon secret access key for the Amazon access key ID that you specified.
-
In the Region field, select the AWS region in which the DynamoDB table resides.
-
In the Table Name field, enter the name of the DynamoDB table that you want this connection to access.
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
DynamoDB West
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample DynamoDB connection that accesses sales data in the western region.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that DynamoDB West appears as a connection that you can choose to add to an integration.
When Syndesis is prompting you to add to an integration, it displays the DynamoDB connection that you just created. This connection always and only accesses the DynamoDB table that you specified when you created the connection.
Obtaining data from an Amazon DynamoDB table
In an integration flow, to obtain an item from an Amazon DynamoDB table, add an Amazon DynamoDB connection to the middle of the flow.
A DynamoDB connection cannot start a simple integration. If you want to periodically obtain data from a DynamoDB table, start a simple integration with a timer followed by a DynamoDB connection that queries a table.
-
You created an Amazon DynamoDB connection.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
In the flow visualization, click the plus sign where you want to add an Amazon DynamoDB connection.
-
On the Choose a connection page, click the Amazon DynamoDB connection that is configured to access that table that you want to obtain data from.
-
On the Choose an action page, select the Query action.
-
In the Filter field, specify JSON notation that identifies the key attribute(s) for the item that the connection should return. You can specify input parameters with
:#
. For example, to obtain an item that has two key attributes, the specification might be something like this:{"key1":":#PARAM1", "key2":":#PARAM2"}
-
Optional. In the Attributes to query field, enter a comma-separated list of the attribute names that contain the data that you want the connection to return. For example:
key1,key2,attribute3,attribute4,attribute5
If you do not specify attributes, the query returns the key attribute(s).
-
Click Next.
The integration now has a DynamoDB connection that obtains data. At runtime, the connection returns a JSON instance document that contains the result of the query.
If you specified placeholder parameters in the Filter field, add a data mapper step before this connection. In the data mapper step, map source fields to the target placeholder fields in the DynamoDB connection.
Adding data to an Amazon DynamoDB table
In the middle of a flow, or to finish a simple integration, a DynamoDB connection can add an item to a DynamoDB table. To do this, add a DynamoDB connection to the middle of a flow or as a simple integration’s finish connection.
| In this release, a DynamoDB connection cannot update an item in a DynamoDB table. This is expected to change in a future release. |
-
You created an Amazon DynamoDB connection.
-
You are creating or editing a simple integration and Syndesis is prompting you to add to the integration or to choose the finish connection.
-
On the Choose a connection page, click the Amazon DynamoDB connection that is configured to access the table that you want to add to.
-
On the Choose an action page, select Put Item.
-
In the JSON definition of the element field, enter JSON notation that defines the table item to be added. You must specify the item’s key attribute(s). Input parameter placeholders prefixed with
:#
are allowed. Be sure to specify all attributes/values that you want to store. In the following example,userID
is the key:{"userID":"aslan","attr1":"some-value","attr2":"another-value"}
-
Click Next.
The connection appears in the integration visualization at the location you added it. During execution, the connection adds the defined JSON item to the DynamoDB table that the connection is configured to access.
If you specified placeholder parameters in the JSON definition of the item, add a data mapper step before this connection. In the data mapper step, map source fields to the target placeholder fields in the DynamoDB connection.
Removing data from an Amazon DynamoDB table
In the middle of a flow, or to finish a simple integration, a DynamoDB connection can remove an item from a DynamoDB table. To do this, add a DynamoDB connection to the middle of a flow or as a simple integration’s finish connection.
-
You created an Amazon DynamoDB connection.
-
You are creating or editing a simple integration and Syndesis is prompting you to add to the integration or to choose the finish connection.
-
On the Choose a connection page, click the Amazon DynamoDB connection that is configured to access the table that contains the item that you want to remove.
-
On the Choose an action page, select Remove Item.
-
In the JSON filter of the element field, enter JSON notation that identifies the item that you want to remove. You must specify the item’s key attribute(s). Input parameters prefixed with
:#
are allowed. In the following example input,userID
is a key attribute:{"userID":"aslan"}
-
Click Next.
The connection appears in the flow visualization where you added it.
If you specified placeholder parameters in the JSON filter of the element field, add a data mapper step before this connection. In the data mapper step, map a source field to each target placeholder field in the DynamoDB connection.
Connecting to Amazon Simple Notification Service (SNS)
An integration can send a message to an AWS Simple Notification Service topic. To do this, create an AWS SNS connection and then add that connection to an integration flow or as the finish connection for a simple integration. For details, see:
Creating Amazon SNS connections
You must create an Amazon SNS connection before you can add an Amazon SNS connection to an integration.
-
AWS access key. See Obtaining AWS credentials.
-
You must know the region in which the SNS topic is located. This is the topic that you want the SNS connection that you are creating to send a message to.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Amazon SNS connector.
-
In the Access Key field, enter an Amazon access key ID that is part of a user access key in the AWS account that manages the topic that you want the connection to send a message to.
If the topic that you want the connection to access does not already exist then when Syndesis tries to start running the integration, it uses the AWS account associated with this access key to create the topic. However, if the topic already exists in some other AWS account, then the connection cannot create the topic and the integration cannot start.
-
In the Secret Key field, enter the Amazon secret access key for the Amazon access key ID that you specified.
-
In the Region field, select the AWS region in which the topic resides. If the connection creates the topic, then it creates it in the selected region.
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
SNS North
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample SNS connection that sends messages to our north region topic.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that SNS North appears as a connection that you can choose to add to an integration.
Sending messages to Amazon SNS
To send a message to an Amazon SNS topic, add an Amazon SNS connection to the middle of a flow or as the finish connection in a simple integration.
-
You created an Amazon SNS connection.
-
Syndesis is prompting you to add to the integration, or to add the finish connection to a simple integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the Amazon SNS connection that you want to use to send a message.
-
Click the Send Object action.
-
In the Topic Name or Amazon Resource Name field, enter the name of the SNS topic to send a message to or enter the topics’s Amazon Resource Name (ARN).
If the SNS topic does not already exist in either the AWS account that the connection is authorized to access, or in any other AWS account, the connection creates the topic in the AWS account that the connection is configured to access.
-
Click Next to add the connection to the integration.
The connection appears in the integration flow where you added it.
Connecting to Amazon Simple Queue Service (SQS)
An integration can retrieve messages from an Amazon SQS queue or send messages to an Amazon SQS queue. To do this, create an Amazon SQS connection and then add that connection to an integration flow. For details, see:
Creating Amazon SQS connections
You must create an Amazon SQS connection before you can add an Amazon SQS connection to an integration.
-
AWS access key. See Obtaining AWS credentials.
-
You must know the region in which the SQS queue is located. This is the queue that you want the SQS connection that you are creating to send messages to or retrieve messages from.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Amazon SQS connector.
-
In the Access Key field, enter an Amazon access key ID that is part of a user access key in the AWS account that manages the queue that you want the connection to access.
If the queue that you want the connection to access does not already exist then when Syndesis tries to start running the integration, it uses the AWS account associated with this access key to create the queue. However, if the queue already exists in some other AWS account, then the connection cannot create the queue and the integration cannot start.
-
In the Secret Key field, enter the Amazon secret access key for the Amazon access key ID that you specified.
-
In the Region field, select the AWS region in which the queue resides. If the connection creates the queue, then it creates it in the selected region.
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
SQS South
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample SQS connection that sends messages to our southern region queue.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that SQS South appears as a connection that you can choose to add to an integration.
Obtaining messages from Amazon SQS to trigger integration execution
To start an integration by obtaining messages from an Amazon SQS queue, add an Amazon SQS connection as a simple integration’s start connection.
-
You created an Amazon SQS connection that is configured to access the queue that you want to obtain messages from.
-
You know the name of the SQS queue that you want the connection to obtain messages from.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Amazon SQS connection that you want to use to start the integration.
-
On the Choose an action page, select Poll an Amazon SQS Queue to periodically retrieve messages from an SQS queue.
-
Configure this action:
-
In the Delay field, accept the default of 500 milliseconds as the time that elapses between polls. Or, to specify a different polling interval, enter a number and select its time unit.
-
In the Maximum Objects to Retrieve field, enter the largest number of messages that one poll operation can obtain. The default is 10.
To have no limit on the number of messages that can be obtained, specify
0
or a negative integer. When Maximum Objects to Retrieve is unlimited, the poll action obtains all messages in the SQS queue. -
In the Queue Name or Amazon Resource Name field, specify the name of the SQS queue to retrieve messages from, or the queue’s ARN. If a queue with this name does not exist, the connection creates it. This is the only required field.
-
Indicate whether you want to Obtain messages and then delete them from the queue. Obtaining messages and then deleting them from the queue is the default behavior. Unselect this option only if you want the connection to retrieve messages and also leave them on the queue, which means that the messages will be retrieved again.
-
Indicate whether you want to Obtain messages and delete the message if it does make it through a Camel filter. This option is selected by default. Leave it selected when you want to pass a retrieved message through a filter to determine whether to delete it from the queue. You do not need to unselect Obtain messages and then delete from the queue. Syndesis ensures the correct behavior when you select Obtain messages and delete the message if it does make it through a Camel filter.
-
-
Click Next.
The connection appears at the beginning of the integration flow.
If you selected Obtain messages and delete the message if it does make it through a Camel filter then you need to add a filter step after this SQS connection. The filter step does not need to be immediately after the SQS connection. Add all connections to the integration, and then add the filter step. During execution, if there are messages that pass the filter, Syndesis uses the same connection, the SQS start connection, to delete those messages from the queue.
Sending messages to an Amazon SQS queue
In the middle of a flow, or to finish a simple integration, you can send messages to an Amazon SQS queue.
-
You created an Amazon SQS connection that is configured to access the queue that you want to send messages to.
-
You know the name of the SQS queue that you want the connection to send messages to.
-
Syndesis is prompting you to add to the integration, or to choose the finish connection for a simple integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the Amazon SQS connection that you want to use to send messages.
-
Select the action that you want the connection to perform:
-
Send Object sends one message to the queue.
-
Send Batch Object sends a batch of messages to the queue.
-
-
In the Message group ID strategy field, for a first-in, first-out (FIFO) queue, accept
ConstantMessageGroupIdStrategy
or click in the field and select a different strategy.The setting of this parameter has no effect on simple queues. The message group ID identifies the group that a message belongs to. Messages that belong to the same message group are always processed one by one, in a strict order relative to the message group. The message group ID strategy determines how the connection assigns a group ID to a message. The options are:
-
ConstantMessageGroupIdStrategy
— The connection uses a constant to group messages. -
ExchangeIdMessageGroupIdStrategy
— The connection uses the exchange ID, which is in each message, to group messages. -
PropertyValueMessageGroupIdStrategy
— The connection uses the value of an internal property to group messages.
FIFO queues are designed to ensure that the order in which messages are sent and received is strictly preserved and that each message is processed exactly once. A FIFO queue name has
.fifo
as a suffix. -
-
In the Message deduplication ID strategy field, for a FIFO queue, accept
NullMessageDeduplicationIdStrategy
or click in the field to selectExchangeIdMessageDeduplicationIdStrategy
.The setting of this parameter has no effect on simple queues. For a FIFO queue, the connection uses the selected strategy to ensure that it does not send duplicate messages to the queue.
-
NullMessageDeduplicationIdStrategy
uses the message body as the deduplication element. In other words, the connection compares message bodies to identify duplicate messages. -
ExchangeIdMessageDeduplicationIdStrategy
uses the message’s exchange ID as the deduplication element. In other words, the connection compares exchange IDs to identify duplicate messages.
-
-
In the Queue Name or Amazon Resource Name field, enter the name of the queue to send messages to. If the queue does not exist, the connection creates it.
-
In the Delay field, accept the default, which is 0 for no delay. Or, to add a delay, specify a number. The integration waits this number of seconds before sending messages. This is useful when the message consumers might not be immediately ready for the messages that the connection is sending.
-
Click Next.
The connection appears in the integration flow where you added it.
Connecting to Amazon Simple Storage Service (S3)
An integration can retrieve data from an Amazon S3 bucket or copy data into an Amazon S3 bucket. To do this, create an Amazon S3 connection and then add that connection to an integration flow. For details, see:
Creating Amazon S3 connections
You must create an Amazon S3 connection before you can add an Amazon S3 connection to an integration.
-
AWS access key. See Obtaining AWS credentials.
-
If the bucket that you want the connection to access already exists, you must know:
-
The region that the bucket is in.
-
The bucket’s name or Amazon Resource Name (ARN).
-
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Amazon S3 connector.
-
In the Access Key field, enter an Amazon access key ID that is part of a user access key in the AWS account that manages the bucket that you want the connection to access.
If the bucket that you want the connection to access does not already exist then when Syndesis tries to start running the integration, it uses the AWS account associated with this access key to create the bucket. However, if the bucket already exists in some other AWS account, then the connection cannot create the bucket and the integration cannot start.
-
In the Secret Key field, enter the Amazon secret access key for the Amazon access key ID that you specified.
-
In the Region field, select the AWS region in which the bucket resides. If the connection creates the bucket, then it creates it in the selected region.
-
In the Bucket Name or Amazon Resource Name field, enter the name of the bucket that you want this connection to access or enter the bucket’s ARN.
If the bucket you specify does not yet exist then the connection tries to create a bucket with the name that you specify. Because S3 allows a bucket to be used as a URL that can be accessed publicly, the bucket name that you specify must be globally unique. Also, it must meet S3 bucket naming requirements.
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Obtain S3 Data
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample S3 connection that obtains data from a northeast bucket.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Obtain S3 Data appears as a connection that you can choose to add to an integration.
Obtaining data from Amazon S3 to trigger integration execution
To start an integration by obtaining data from an Amazon S3 bucket, add an Amazon S3 connection as a simple integration’s start connection.
You created an Amazon S3 connection.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Amazon S3 connection that you want to use to start the integration.
-
On the Choose an action page, select the action that you want the connection to perform:
-
Get Object obtains a file from the bucket that the connection accesses. In the File Name field, enter the name of the file that you want to obtain. If the specified file is not in the bucket, it is a runtime error.
-
Poll an Amazon S3 Bucket periodically obtains files from the bucket that the connection accesses. To configure this action:
-
In the Delay field, accept the default of 500 milliseconds as the time that elapses between polls. Or, to specify a different polling interval, enter a number and select its time unit.
-
In the Maximum Objects to Retrieve field, enter the largest number of files that one poll operation can obtain. The default is 10.
To have no limit on the number of files that can be obtained, specify
0
or a negative integer. When Maximum Objects to Retrieve is unlimited, the poll action obtains all files in the bucket.If the bucket contains more than the specified maximum number of files then the action obtains the files that were most recently modified or created.
-
In the Prefix field, optionally specify a regular expression that evaluates to a string. If you specify a prefix then this action retrieves a file only when its name starts with that string.
-
Indicate whether you want to Obtain files and then delete them from the bucket.
-
-
-
After you configure the action, click Next to specify the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The integration now has a start connection and Syndesis is prompting you to choose the finish connection.
Adding data to Amazon S3 to finish an integration
To finish an integration by copying data to Amazon S3, add an Amazon S3 connection as a simple integration’s finish connection.
-
You created an Amazon S3 connection.
-
You are creating or editing a simple integration and Syndesis is prompting you to choose a finish connection.
-
On the Choose a connection page, click the Amazon S3 connection that you want to use to finish the integration.
-
Select the action that you want the connection to perform:
-
Copy Object adds one or more objects to the bucket.
To add one file to the bucket, you can enter its name in the File Name field.
To add multiple files to the bucket, do not specify a file name. In this case, the action adds all objects that it obtains from the previous integration step(s).
If you used the poll action to obtain multiple files and you specify a file name then the Copy Object action adds only the last file that was received from the poll action.
-
Delete Object deletes an object from the bucket. In the File Name field, specify the name of the object that you want to delete. If the specified file is not in the bucket, the integration continues with no error.
-
-
After you configure the chosen action, click Next to specify the action’s input type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the end of the integration visualization.
Adding data to Amazon S3 in the middle of an integration
In the middle of an integration, to add data to Amazon S3, add an Amazon S3 connection to the middle of a flow.
-
You created an Amazon S3 connection.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
In the flow visualization, click the plus sign where you want to add an Amazon S3 connection.
-
Click the Amazon S3 connection that you want to use in the middle of a flow.
-
Select the action that you want the connection to perform:
-
Copy Object adds one or more objects to the bucket.
To add one file to the bucket, you can enter its name in the File Name field.
To add multiple files to the bucket, do not specify a file name. In this case, the action adds all objects that it obtains from the previous integration step(s).
If you used the poll action to obtain multiple files and you specify a file name then the Copy Object action adds only the last file that was received from the poll action.
-
Delete Object deletes an object from the bucket. In the File Name field, specify the name of the object that you want to delete. If the specified file is not in the bucket, the integration continues with no error.
-
-
After you configure the chosen action, click Next to specify the action’s input type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears in the flow visualization where you added it.
Connecting to AMQ
In an integration, you can obtain messages from a Red Hat AMQ broker or publish messages to a Red Hat AMQ broker. Red Hat AMQ uses the OpenWire protocol for communication between clients and message brokers. To communicate with the following broker types, use the Red Hat AMQ connector to create a connection to the broker of interest:
-
Apache ActiveMQ broker that does not support AMQP
-
AMQ 6 broker
To communicate with one of the following broker types, use the AMQP connector to create a connection to the broker of interest:
-
Apache ActiveMQ broker that supports AMQP
-
Apache ActiveMQ Artemis
-
AMQ 7 broker
-
EnMasse, which is an open source messaging platform
To use the Red Hat AMQ connector, see:
Creating an AMQ connection
In an integration, to obtain messages from or to publish messages to:
-
An Apache ActiveMQ broker that does not support AMQP
-
An AMQ 6 broker
Create a Red Hat AMQ connection, which you can add to an integration.
For the Red Hat AMQ broker that you want to connect to, you have the following:
-
Broker URL
-
User account credentials
-
Broker’s PEM certificate text
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display connectors.
-
Click the Red Hat AMQ connector.
-
Configure the connection:
-
In the Broker URL field, enter the location that you want to send data to or obtain data from, for example,
tcp://localhost:61616
. -
In the User name field, enter the user name for the account that you want to use to access this broker.
-
In the Password field, enter the password for the account that you want to use to access this broker.
-
In the Client ID field, enter the ID that allows connections to close and reopen without missing messages. The destination type must be a topic.
-
If this connection will be used in a development environment, you can save some time by disabling Check certificates. Disabling the checking of certificates is a convenience for development environments. For secure production environments, always enable Check certificates.
-
In the Broker certificate field, paste the Red Hat AMQ broker’s PEM certificate text. This is required except when you disable checking the certificates.
-
In the Client certificate field, paste the Red Hat client’s PEM certificate text. Content in this field is always optional.
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the configuration details as needed and try again.
-
If validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter
Red Hat AMQ 1
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Red Hat AMQ connection that uses a provided broker.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Red Hat AMQ 1 appears as a connection that you can choose to add to an integration.
Adding an AMQ connection to trigger integration execution upon receiving messages
To trigger execution of an integration upon receiving a message from a Red Hat AMQ broker, add a Red Hat AMQ connection as the start connection.
You created a Red Hat AMQ connection to the Red Hat AMQ broker that you want to obtain messages from.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Red Hat AMQ connection that you want to use to start the integration.
-
On the Choose an action page, select the Subscribe for messages action to receive messages from the queue or topic that you specify.
-
Configure the action:
-
In the Destination name field, enter the name of the queue or topic to receive data from.
-
For the Destination type, accept Queue or select Topic.
-
In the Durable subscription ID field, to allow connections to close and reopen without missing messages, enter the durable subscription ID. The destination type must be a topic.
-
In the Message selector field, if you want to receive only data that satisfies a particular condition, enter a filter expression.
A message selector is a string that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. The message selector in the following example selects any message that has a
NewsType
property whose value is set toSports
orOpinion
:NewsType = ’Sports’ OR NewsType = ’Opinion’
The message consumer receives only those messages whose headers and properties match the message selector expression. A message selector cannot select messages on the basis of the content of the message body.
-
-
Click Next to specify the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the beginning of the integration flow.
Publishing AMQ messages to finish an integration
To finish a simple integration by publishing messages to a Red Hat AMQ broker, add a Red Hat AMQ connection as the simple integration’s finish connection.
-
You created a connection to the Red Hat AMQ broker that you want to publish messages to.
-
You are creating an integration and Syndesis is prompting you to choose the finish connection, or you are editing an integration to change the finish connection.
-
On the Choose a connection page, click the Red Hat AMQ connection that you want to use to finish the integration.
-
On the Choose an action page, select the Publish messages action to publish messages to the queue or topic that you specify.
-
In the Destination name field, enter the name of the queue or topic to send messages to.
-
For the Destination type, accept Queue or select Topic.
-
Select Persistent to guarantee message delivery even if a connection fails.
-
Click Next to specify the action’s input/output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input/output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the end of the integration visualization.
Publishing AMQ messages in the middle of an integration
In the middle of an integration, to publish messages to a Red Hat AMQ broker, add a Red Hat AMQ connection to the middle of a flow.
-
You created a connection to the Red Hat AMQ broker that you want to publish messages to.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to choose a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the Red Hat AMQ connection that you want in the middle of the flow.
-
On the Choose an action page, select one of the following actions:
-
Publish messages to publish messages to the queue or topic that you specify. To configure this action:
-
In the Destination name field, enter the name of the queue or topic to send messages to.
-
For the Destination type, accept Queue or select Topic.
-
Select Persistent to guarantee message delivery even if a connection fails.
-
-
Request response using messages to send messages to the JMS destination that you specify and receive a response. To configure this action:
-
In the Destination name field, enter the name of the queue or topic to send messages to.
-
For the Destination type, accept Queue or select Topic.
-
In the Message selector field, if you want to receive only responses that satisfy a particular condition, enter a filter expression.
A message selector is a string that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. The message selector in the following example selects any message that has a
NewsType
property whose value is set toSports
orOpinion
:NewsType = ’Sports’ OR NewsType = ’Opinion’
The message consumer receives only those messages whose headers and properties match the message selector expression. A message selector cannot select messages on the basis of the content of the message body.
-
In the Named reply to field, enter the name of a queue or topic. The destination sends its response to this queue or topic.
-
Select Persistent to guarantee message delivery even if a connection fails.
-
In the Response time out field, specify the number of milliseconds that this connection waits for a response message before throwing a runtime exception. The default is 5000 milliseconds (5 seconds).
-
-
-
Click Next to specify the action’s input type and then the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input/output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears in the integration visualization where you added it.
Connecting to AMQP
In an integration, you can obtain messages from or publish messages to an Advanced Message Queue Protocol (AMQP) broker. AMQP defines communication between clients and message brokers. To communicate with the following broker types, use the AMQP connector to create a connection to the broker of interest:
-
Apache ActiveMQ broker that supports AMQP
-
Apache ActiveMQ Artemis
-
AMQ 7 broker
-
EnMasse, which is an open source messaging platform
To communicate with one of the following broker types, use the Red Hat AMQ connector to create a connection to the broker of interest:
-
Apache ActiveMQ broker that does not support AMQP
-
AMQ 6 broker
| It is possible to use the AMQP connector to create a connection to an Apache ActiveMQ broker that does not support AMQP or to an AMQ 6 broker. Doing this requires transport configuration in the broker. For information about configuring the broker, see Red Hat JBoss A-MQ Managing and Monitoring Brokers, Adding Client Connection Points. For information about the configuration values to specify, see Red Hat JBoss A-MQ Connection Reference, Advanced Message Queuing Protocol (AMQP). |
To use the AMQP connector, see:
Creating an AMQP connection
In an integration, to obtain messages from or publish messages to an AMQP broker, create an AMQP connection, which you can add to an integration.
For the AMQP broker that you want to connect to, you have the following:
-
Its URI
-
User account credentials
-
Its PEM certificate text
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display connectors.
-
Click the AMQP Message Broker connector.
-
Configure the connection:
-
In the Connection URI field, enter the location you want to send data to or obtain data from.
-
In the User name field, enter the user name for the account that you want to use to access this broker.
-
In the Password field, enter the password for the account that you want to use to access this broker.
-
In the Client ID field, enter the ID that allows connections to close and reopen without missing messages. The destination type must be a topic.
-
If this connection will be used in a development environment, you can save some time by disabling Check certificates. Disabling the checking of certificates is a convenience for development environments. For secure production environments, always enable Check certificates.
-
In the Broker certificate field, paste the broker’s PEM certificate text. This is required except when you disable the checking of certificates.
-
In the Client certificate field, paste the client’s PEM certificate text. Content in this field is always optional.
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the configuration details as needed and try again.
-
If validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter
AMQP 1
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample AMQP connection
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that AMQP 1 appears as a connection that you can choose to add to an integration.
Adding an AMQP connection to trigger integration execution upon receiving messages
To trigger execution of an integration upon receiving messages from an AMQP broker, add an AMQP connection as the integration’s start connection.
-
You created a connection to the AMQP broker that you want to receive messages from.
-
You are creating an integration and Syndesis is prompting you to choose the start connection.
-
On the Choose a connection page, click the AMQP connection that you want to use to start the integration.
-
On the Choose an action page, select the Subscribe for messages action to receive messages from the queue or topic that you specify.
-
Configure the action:
-
In the Destination name field, enter the name of the queue or topic to receive data from.
-
For the Destination type, accept Queue or select Topic.
-
In the Durable subscription ID field, to allow connections to close and reopen without missing messages, enter the durable subscription ID. The destination type must be a topic.
-
In the Message selector field, if you want to receive only data that satisfies a particular condition, enter a filter expression.
A message selector is a string that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. The message selector in the following example selects any message that has a
NewsType
property whose value is set toSports
orOpinion
:NewsType = ’Sports’ OR NewsType = ’Opinion’
The message consumer receives only those messages whose headers and properties match the message selector expression. A message selector cannot select messages on the basis of the content of the message body.
-
-
Click Next to specify the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the beginning of the integration flow.
Publishing messages to AMQP in the middle of a flow or to finish an integration
You can publish messages to an AMQP broker in the middle of a flow or to finish a simple integration. To do this, add an AMQP connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a connection to the AMQP broker that you want to publish messages to.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to choose a simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the AMQP connection that you want to use to publish messages.
-
On the Choose an action page, select one of the following actions:
-
Publish messages to publish messages to the queue or topic that you specify without receiving a response. To configure this action:
-
In the Destination name field, enter the name of the queue or topic to send messages to.
-
For the Destination type, accept Queue or select Topic.
-
Select Persistent to guarantee message delivery even if a connection fails.
-
-
Request response using messages to publish messages to the queue or topic that you specify and receive a response.
When the finish connection in a simple integration is an AMQP connection that performs the Request response using messages action, the connection publishes the messages but the response is discarded. To avoid losing the response, add an AMQP connection as a middle connection that performs the Request response using messages action and finish the simple integration with a log step.
To configure this action:
-
In the Destination name field, enter the name of the queue or topic to send messages to.
-
For the Destination type, accept Queue or select Topic.
-
In the Durable subscription ID field, to allow connections to close and reopen without missing messages, enter the durable subscription ID. The destination type must be a topic.
-
In the Message selector field, if you want to receive only responses that satisfy a particular condition, enter a filter expression.
A message selector is a string that contains an expression. The syntax of the expression is based on a subset of the SQL92 conditional expression syntax. The message selector in the following example selects any message that has a
NewsType
property whose value is set toSports
orOpinion
:NewsType = ’Sports’ OR NewsType = ’Opinion’
The message consumer receives only those messages whose headers and properties match the message selector expression. A message selector cannot select messages on the basis of the content of the message body.
-
-
-
Click Next to specify the action’s input and output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input/output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears in the integration visualization where you added it.
Connecting to Box
In an integration, you can download files from Box or upload files to Box.
A connection to Box cannot start a simple integration. In other words, you cannot use a Box connection to trigger integration execution.
The following topics provide the details:
Registering Syndesis as a Box client
You must register your Syndesis environment as a client application that can access Box. This lets you create any number of integrations that connect to Box. In other words, you need to register a particular Syndesis environment with Box only once.
In each Syndesis environment, there can be only one registration of Syndesis as a Box client application. However, while each Box connection uses the same registration, it can use different user credentials.
-
You have a Box developer account, which you can obtain at https://app.box.com/developers/console.
-
In Syndesis:
-
In the left panel, click Settings.
-
On the Settings page, near the top, to the right of the callback URL, click to copy the callback URL for your Syndesis environment to the clipboard. You will need this URL toward the end of this procedure.
-
-
In another browser tab, go to the Box developer portal at https://app.box.com/developers/console and do the following:
-
Sign in.
-
Click Create New App.
-
Click Custom App and then Next.
-
For Authentication Method, click Standard OAuth 2.0 (User Authentication) and then Next.
-
Enter an app name, for example, Syndesis Client and click Create App.
-
Click View Your App.
-
Optional. In the OAuth 2.0 Credentials section, copy the client ID and the client secret to a safe location. These values are needed to create a connection to Box.
-
Click Save Changes.
-
Your Syndesis environment is now registered as a Box client, which means that Syndesis can access content in the Box account that you signed into.
Creating a Box connection
In an integration, to download or upload Box files, create a Box connection, which you can add to an integration. You can add the same connection to any number of integrations.
-
There is a Box client application that registers your Syndesis environment as an application that can access Box.
-
You can log in to the Box developer account that created that application, or you have the Box client ID and Box client secret for that application.
-
You know the user name and password for the Box account that you want this connection to use to access Box.
-
If you already have the Box client ID and the client secret, skip to the next step. Otherwise, to obtain those values, in a new browser tab, go to https://app.box.com/developers/console and do the following:
-
Sign in to the Box account in which you created the app that registers access to Box from your Syndesis environment.
-
On the My Apps page, click the Syndesis app to display its settings.
-
On the left, click Configuration.
-
In the OAuth 2.0 Credentials section, copy the client ID to the clipboard.
-
-
In a different browser tab, in Syndesis:
-
Click Connections.
-
Click Create Connection.
-
Click the Box connector.
-
In the User name field, enter the user name for the Box account that you want this connection to use to download or upload Box files.
-
In the User password field, enter the password for that account.
-
In the Client ID field, paste the Box client ID.
-
-
Optional. If you need to, go back to the OAuth 2.0 Credentials for the Box app, copy the client secret to the clipboard and then return to Syndesis.
-
In the Client secret field, paste the Box client secret string.
-
Click Validate. Syndesis displays a message that indicates whether it can validate this connection. If validation fails, try again and be sure to enter the correct values.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Box Sales Account
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Box connection that can access content in our company sales Box account.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Box Sales Account appears as a connection that you can choose to add to an integration.
Downloading or uploading a Box file in the middle of an integration
To download a file from Box, or upload a file to Box in the middle of a flow, add a Box connection to the middle of the flow.
-
You created a Box connection.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection.
-
Click the Box connection that you want the integration to use.
-
On the Choose an action page, select one of the following:
-
Download to obtain a file from the Box account that this connection accesses.
-
Upload to upload a file to the Box account that this connection accesses.
-
-
Configure the action you selected.
To download a file:
-
In the File encoding field, accept
UTF-8
or specify the encoding for the file that you want the connection to obtain. -
Optional. In the File ID field, specify the Box ID for the file that you want to obtain. The file ID is at the end of the URL when you are viewing the file in Box. For example, in this URL:
https://app.box.com/file/537364588548
, the file ID is537364588548
.Alternatively, you can add a data mapper step before this connection and map the file ID from a previous step to this connection.
In this release, you can download only a single file. However, mapping the file ID from a previous step can make identification of the file dynamic, for example, the ID can come from a database table. This means each execution might download a different file.
To upload a file:
-
In the Parent folder ID field, enter the ID of the Box folder to upload the file to.
Box folder IDs are at the end of the URL when you view the content of a folder in Box. In this example:
https://app.box.com/folder/89490291417
, the folder ID is89490291417
. In this release, you can upload only a single file. -
Optional. In the File name field, enter the name for a new file. If you specify the name of a file that is already in the specified Box folder, the connection overwrites the file that is in the folder.
The input to the connection must be a file that you want to upload to Box. If you do not specify a file name, the connection uploads a file that has the same name as the input file to the connection as long as a file with that name is not already present.
-
Click Next to specify the upload action’s input type.
-
In the Select Type field, accept Type specification not required and click Next.
-
The connection appears in the integration flow where you added it.
Uploading files to Box to finish an integration
To finish an integration by uploading files to Box, add a Box connection as the integration’s finish connection.
-
You created a Box connection.
-
You are creating or editing a simple integration and Syndesis is prompting you to choose the finish connection.
-
On the Choose a connection page, click the Box connection that you want to use to finish the integration.
-
On the Choose an action page, select the Upload action to upload a file to the Box account that this connection accesses.
-
In the Parent folder ID field, enter the ID of the Box folder to upload the file to.
Box folder IDs are at the end of the URL when you select a folder in Box. In this example:
https://app.box.com/folder/89490291417
, the folder ID is89490291417
. In this release, you can upload only a single file. -
Optional. In the File name field, enter the name for a new file or an existing file. If you specify the name of a file that is already in the specified Box folder, the connection overwrites the file that is in the folder.
The input to the connection must be a file that you want to upload to Box. If you do not specify a file name, the connection uploads a file that has the same name as the input file to the connection.
-
Click Next.
-
In the Select Type field, accept Type specification not required and click Next.
The connection appears at the end of the integration visualization.
Connecting to Dropbox
In an integration, you can download files from Dropbox or upload files to Dropbox. The following topics provide the details:
Registering Syndesis as a Dropbox client
You must register your Syndesis environment as a client application that can access Dropbox. This lets you create any number of integrations that connect to Dropbox. In other words, you need to register a particular Syndesis environment with Dropbox only once.
In each Syndesis environment, there can be only one registration of Syndesis as a Dropbox client application. However, while each Dropbox connection uses the same registration, it can use different user credentials.
You can sign in to the Dropbox account that you want an integration to use to download or upload files.
-
In Syndesis:
-
In the left panel, click Settings.
-
On the Settings page, near the top, to the right of the callback URL, click to copy the callback URL for your Syndesis environment to the clipboard. You will need this URL toward the end of this procedure.
-
-
In another browser tab, go to
https://www.dropbox.com
and do the following:-
Sign in to the Dropbox account that has the data that you want to access in an integration.
-
After signing in, go to https://www.dropbox.com/developers/apps.
-
Click Create App.
-
Select Dropbox API.
-
Near the top of the page, in the sentence that starts with
During registration, enter this callback URL:
, paste the URL that you copied to the clipboard at the beginning of this procedure. For example, the URL that you paste is something like this:https://app-proj9128.7b63.fuse-ignite.openshiftapps.com/api/v1/credentials/callback
. -
Choose whether Syndesis can access a single folder or all of the folders and files.
-
Specify a name for your Dropbox app. For example, you might specify
Fuse Online Access From Aslan LLC
. The name you specify must be unique in the set of Dropbox app names. -
Check the box to indicate that you agree to Dropbox API terms and conditions.
-
Click Create App.
-
In the Dropbox Settings page for your new app, in the input field for OAuth2 Redirect URIs, paste your Syndesis URL, which you copied to the clipboard at the beginning of this procedure.
-
Click Add.
-
Your Syndesis environment is now registered as a Dropbox client, which means that Syndesis can access content in the Dropbox account that you signed into.
Creating a Dropbox connection
In an integration, to download or upload Dropbox files, create a Dropbox connection, which you can add to an integration. You can add the same connection to any number of integrations.
You registered your Syndesis environment as an application that can access Dropbox.
-
In a new browser tab, go to
https://www.dropbox.com
and do the following:-
Sign in to the Dropbox account in which you created the app that registers access from your Syndesis environment.
-
Click the Syndesis app to display its settings.
-
-
In another browser tab, in Syndesis, do the following:
-
In the left panel, click Connections to display any available connections.
-
Click Create Connection to display the available connectors.
-
Click the Dropbox connector.
-
-
Go back to the Dropbox settings display for your app and do the following:
-
Scroll down to see Generated Access Token.
-
Click Generate.
-
Copy the generated access token to the clipboard.
-
-
Back in Syndesis, in the Configure Connection page, in the Access Token field, paste the generated access token.
-
In the Client Identifier field, enter the name that you specified when you created the Dropbox app.
-
Click Validate. Syndesis displays a message that indicates whether it can validate this connection. If validation fails, try again and be sure to enter the correct values.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Dropbox Connect 1
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Dropbox connection that can access all content in our company Dropbox account.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Dropbox Connect 1 appears as a connection that you can choose to add to an integration.
Obtaining files from Dropbox to trigger integration execution
To start an integration by downloading files from Dropbox, add a Dropbox connection as the start connection.
You created a Dropbox connection.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Dropbox connection that you want to use to start the integration.
-
On the Choose an action page, select the Download action to obtain one or more files from the Dropbox account that this connection accesses.
-
To configure the action, in the Folder or file name path to download field, specify the filename path for the content that you want the integration to obtain. In this release, you can download only a single file.
-
Click Next to specify the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection starts the simple integration and Syndesis prompts you to choose the finish connection.
Adding files to Dropbox to finish an integration
To finish an integration by uploading files to Dropbox, add a Dropbox connection as the integration’s finish connection.
-
You created a Dropbox connection.
-
You are creating or editing an integration and Syndesis is prompting you to choose the finish connection.
-
On the Choose a connection page, click the Dropbox connection that you want to use to finish the integration.
-
On the Choose an action page, select the Upload action to add the current integration data to the Dropbox account that this connection accesses.
-
In the Remote Path field, enter the local filename path for file that you want to upload. Dropbox stores the file with the same path and name. In this release, you can upload only a single file.
-
For the Upload mode:
-
Select Add to upload a file only when a file with the same name is not already in the same Dropbox folder. If a file with the same name is already in the same Dropbox folder, then the file is not uploaded and the integration continues. This is the behavior regardless of whether the content in the file you are trying to upload has been updated.
-
Select Force to ensure that the file is uploaded even if a file with the same name is present in the same Dropbox folder. Dropbox overwrites the file that it already has with the file that you are uploading.
-
-
Click Next to specify the action’s input type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the end of the integration visualization.
Accessing Dropbox in the middle of an integration
To upload a file to Dropbox in the middle of a flow, add a Dropbox connection to the middle of the flow.
-
You created a Dropbox connection.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the Dropbox connection that you want the integration to use.
-
On the Choose an action page, select Upload to add the current integration data to the Dropbox account that this connection accesses.
-
Configure this action:
-
In the Remote Path field, specify the local path and file name of the file that you want to upload. Dropbox stores the file with the same path and name. In this release, you can upload only a single file.
-
For the Upload mode:
-
Select Add to upload a file only when a file with the same name is not already in the same Dropbox folder. If a file with the same name is already in the same Dropbox folder, then the file is not uploaded and the integration continues. This is the behavior regardless of whether the content in the file you are trying to upload has been updated.
-
Select Force to ensure that the file is uploaded even if a file with the same name is present in the same Dropbox folder. Dropbox overwrites the file that it already has with the file that you are uploading.
-
-
-
Click Next to specify the action’s input and output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection input/output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears in the integration flow where you added it.
Connecting to Email Servers (IMAP, POP3, SMTP)
An integration can connect to an IMAP or POP3 email server to retrieve email messages or connect to an SMTP email server to send email messages. To trigger integration execution upon retrieving email, create a connection to an IMAP or POP3 email server and then add that connection as a simple integration’s start connection. To send an email from a flow, create a connection to an SMTP email server and then add that connection to the middle of a flow or to finish a simple integration.
For details, see:
Creating a connection to an IMAP or POP3 email server
You must create a connection to an IMAP or POP3 email server before you can create a simple integration whose execution is triggered by received email.
You must be familiar with the email server that this connection accesses. Specifically, you must know:
-
Whether the email server uses the IMAP or POP3 protocol.
-
Whether authentication credentials are required. If they are, you must have a user name and password.
-
Whether a security method is implemented. If one is, you must know which method.
-
Whether a server certificate is required. If it is, you must be able to specify it.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Receive Email connector.
-
Configure the connection:
-
In the Protocol field, accept imap or select pop3.
-
In the Email Host Name field, enter the email server host name, virtual host name, or IP address.
-
In the Email Server Port Number field, enter the port number that the email server listens on.
-
In the User Name field, specify the user name for the email account that this connection is authorized to access. During execution of an integration, this connection polls this email account for messages.
Rarely, an email server does not authenticate access. In that case, specification of user name and password is not required.
-
In the Password field, specify the password for the email account that this connection is authorized to access.
-
Optional. In the Security Method field, if the email server implements a security method, select StartTLS or SSL/TLS.
-
Optional. In the Server Certificate field, if the email server is not public, that is, it is on an internal network, and if you selected StartTLS or SSL/TLS as the security method, paste the self-signed email server certificate in this field. Syndesis cannot verify this connection if a server certificate is required and you do not specify it.
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Obtain Info Emails
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Connect to our company email server to obtain messages sent to<EMAIL_ADDRESS>-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Obtain Info Emails appears as a connection that you can choose to add to an integration.
Creating a connection to an SMTP email server
You must create a connection to an SMTP email server before you can edit an integration flow so that it connects to an SMTP email server to send email.
You must be familiar with the email server that this connection accesses. Specifically, you must know:
-
Whether authentication credentials are required. If they are, you must have a user name and password.
-
Whether a security method is implemented. If one is, you must know which method.
-
Whether a server certificate is required. If it is, you must be able to specify it.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the Send Email connector.
-
Configure the connection:
-
In the Email Host Name field, enter the email server host name, virtual host name, or IP address.
-
In the Email Server Port Number field, enter the port number that the email server listens on.
-
In the User Name field, specify the user name for the email account that this connection is authorized to access. During execution of an integration, this connection uses this email account to send messages.
Rarely, an email server does not authenticate access. In that case, specification of user name and password is not required.
-
In the Password field, specify the password for the email account that this connection is authorized to access.
-
Optional. In the Security Method field, if the email server implements a security method, select StartTLS or SSL/TLS.
-
Optional. In the Server Certificate field, if the email server is not public, that is, it is on an internal network, and if you selected StartTLS or SSL/TLS as the security method, paste the self-signed email server certificate in this field. Syndesis cannot verify this connection if a server certificate is required and you do not specify it.
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Send Emails to Leads
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Connect to our company email server to send messages from<EMAIL_ADDRESS>-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Send Emails to Leads appears as a connection that you can choose to add to an integration.
Obtaining email to trigger integration execution
To trigger execution of an integration upon receiving email, add an IMAP or POP3 email server connection as a simple integration’s start connection.
-
You created an IMAP or POP3 email server connection that is configured to access the account that you want to obtain email from.
-
You know the name of the folder to retrieve messages from.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the email server connection that you want to use to start the integration.
-
On the Choose an action page, select Receive Email to periodically retrieve messages from the email account that the connection is authorized to access.
-
Configure the action:
-
Leave the Folder field blank to obtain email from the inbox. Or, to obtain messages from a particular folder, enter the name of that folder.
If this connection accesses a POP3 email server, only standard folders, such as Inbox or Sent are supported.
-
Select the Unseen Only checkbox to obtain only messages that are marked as unread on the email server.
-
In the Delay field, accept the default of 5 seconds as the time that elapses between polls for messages. Or, to specify a different polling interval, enter a number and select its time unit.
-
In the Maximum Emails field, enter the largest number of messages that one poll operation can return. The default is 5. If the inbox or folder contains more than the maximum number of messages that can be returned, the connection returns the oldest messages up to the number set for Maximum Emails.
Set Maximum Emails to
-1
if you want each poll to obtain:-
All new messages in the specified folder when Unseen Only is selected.
-
All messages in the specified folder when Unseen Only is NOT selected.
-
-
-
Click Next.
The connection appears at the beginning of the integration flow. During execution, if a poll returns email, the connection passes the messages to the next step in the integration. If a poll does not return any email, the integration continues to run but Syndesis does not trigger the rest of the integration steps.
Consider a Receive Email action that is configured as follows:
-
The Folder field is blank so the connection polls the inbox.
-
Unseen Only is selected.
-
The defaults for Delay (5 seconds) and Maximum Emails (5) are accepted.
Suppose that 10 messages arrive in the inbox during the delay before the next poll. The connection returns the 5 oldest messages. At the next poll, 5 seconds later, the connection returns the other 5 messages. Even if new messages arrived, this is the case because the connection returns the oldest messages if there are more messages than the number set for Maximum Emails.
Sending email from an integration
In the middle of a flow, or to finish a simple integration, you can add an email server connection that sends messages.
-
You created an SMTP email server connection that is configured to access the account that you want to send messages from.
-
Syndesis is prompting you to add to the integration, or to choose the finish connection for a simple integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the email server connection that you want to use to send messages.
-
Select the Send Email action.
-
In the Email from field, enter the email address that sends the messages. This is required even if you plan to add a data mapper step that maps an email address from a previous integration step to this connection.
-
Recommended: Specify a value in each of the following fields. Separate multiple email addresses with a comma.
-
Email to
-
Email subject
-
Email text
-
Email cc
-
Email bcc
-
-
In the Parameter Priority field, accept Input Values or select Consumed Data. This determines which of the following has precedence:
-
Input values in this action configuration
-
Data values that you map to this connection
The recommendation is to select Consumed Data. This means that the values that you specify in the email fields here serve as default values.
-
-
Click Next to add the connection to the flow.
The connection appears in the integration flow where you added it.
Add all other needed to connections to the flow. Then add a data mapper step before the connection that sends email. In the data mapper step, map source fields to the target fields for sending emails.
Connecting to FHIR
Fast Healthcare Interoperability Resources (FHIR) is a standard for exchanging healthcare data. In an integration, you can obtain one or more FHIR resources, create or update a resource, update one or more fields in a resource, or use a transaction to create multiple resources. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.
Syndesis connections to FHIR:
-
Can communicate with FHIR servers that use basic or bearer token (OAuth) authentication.
-
Can operate on all FHIR resources that comply with FHIR DSTU3.
-
Cannot operate on extensions, which allow for storing custom data in a resource. If an extension is in data that is received from a FHIR server, the integration silently ignores it.
In an integration that connects to FHIR, in a data mapper step, you can map only one level of depth for a FHIR list field. In other words, if a FHIR list contains a list then you cannot map the fields in the nested list. To mitigate this limitation, Syndesis converts some FHIR resource list fields to single-value fields, for example, an address that is in a list field might be displayed in the data mapper as a single field.
Details for connecting to FHIR are in the following topics:
Creating a connection to a FHIR server
In an integration, to operate on FHIR resources, create a connection to a FHIR server and then add that connection to the middle of a flow or as a simple integration’s finish connection.
A FHIR connection cannot be the start connection of a simple integration. However, you can start a simple integration with a timer that periodically triggers a FHIR connection.
-
You must know the URL for the FHIR server that you want to connect to.
-
You must have authorization credentials for accessing the FHIR server. You should obtain these from the FHIR server administrator. Rarely, a FHIR server does not require authentication and you can create a connection without specifying credentials. For example, a public FHIR server or a FHIR server in a private network might not require authentication.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display connectors.
-
Click the FHIR connector and configure the connection as follows:
-
In the FHIR version field, accept DSTU3, which is required.
-
In the FHIR server URL field, enter the URL for the FHIR server that you want to access. While creating an integration, you might accept the default test server
http://fhirtest.uhn.ca/baseDstu3
. -
In the FHIR server username field, enter your username. This is required by FHIR servers that use basic authentication.
-
In the FHIR server password field, enter your password, which is also required by FHIR servers that use basic authentication.
-
In the FHIR server bearer token field, enter your token. This is required by FHIR servers that use OAuth authentication.
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the input parameters and try again.
-
If validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, you might enter
FHIR West
. -
In the Description field, optionally enter any information that is helpful to know about this connection.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that FHIR West appears as a connection that you can choose to add to an integration.
Obtaining a resource from a FHIR server
In an integration, you can obtain one resource that is of the type that you specify. To do this, add a FHIR connection to the middle of a flow.
-
You created a connection to the FHIR server that has the resource that you want to obtain.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection.
-
Click the FHIR connection that can access the resource that you want to obtain.
-
On the Choose an action page, select Read.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to obtain.
-
In the Contained Resource Types field, if the resource type that you want contains other resource types, select them. Use the Ctrl key if you need to select more than one.
Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.
-
In the Resource Id field, enter the ID of the resource that you want. Or, leave this field blank if you plan to map it from an earlier step that is in the flow.
-
In the Resource version field, optionally specify a version ID for the resource. Leave this field blank to obtain the most recent version of the resource or to map the version ID of the resource that you want to obtain from a previous step.
-
Click Next to add this connection to the flow.
The connection appears in the integration visualization where you added it. During execution, this connection returns one resource.
To map a value to the Resource Id field or the Resource version field, add a data mapper step before this connection.
Querying a FHIR server for resources
In an integration, you can query a FHIR server to obtain instances of a particular FHIR resource that satisfy a query that you specify. For example, suppose you want to ensure that all patients who are 65 and older received a pneumonia vaccination. Specify a query that obtains the resources for patients who were born before 1955. To do this, add a FHIR connection to the middle of a flow.
-
You created a connection to the FHIR server that has the resources that you want to obtain.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration.
-
On the Add to Integration page, click the plus sign where you want to add the connection.
-
Click the FHIR connection that has the resources that you want to obtain.
-
On the Choose an action page, select Search.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to obtain.
-
In the Query field, specify a FHIR query or leave this field blank to map the query from a previous step. For details about forming a FHIR query, see FHIR Release 3 Search.
-
Click Next to add this connection to the flow.
The connection appears in the integration visualization where you added it. During execution, this connection returns a list of resources that satisfy the query that you specified. Syndesis treats this list as a collection.
If you did not specify a query, then add a data mapper step before this connection and map the query to this connection. To operate on individual returned resources, rather than on the returned list collection, after this connection, add a split step to the flow.
Creating a resource on a FHIR server
In an integration, you can create and add a resource to a FHIR server. When you configure the connection’s Create action, you specify the type of the resource that you want to create. For example, you might want to add a new patient resource to a FHIR server. To create a resource, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.
To populate the values in the new resource, add a data mapper step to the flow just before the FHIR connection that you are adding in this procedure. It is expected that the previous steps in the flow provide the data that you want the new resource to contain. Map fields in the previous steps to fields in the target resource that this FHIR connection is creating. The new resource contains only the fields that you map to.
When a connection performs the Create action to create a new resource on a FHIR server, the new resource has an automatically-generated FHIR resource ID. If you want to specify the resource ID for a new resource, instead of selecting the Create action choose the Update action for the connection to perform.
-
You created a connection to the FHIR server that you want to add a resource to.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to add a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FHIR connection to the server that you want to add a resource to.
-
On the Choose an action page, select Create.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to create.
-
In the Contained Resource Types field, if the resource type that you want to create contains other resource types, select them. Use the Ctrl key if you need to select more than one.
Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map to or from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.
-
Click Next to add this connection to the flow.
The connection appears in the integration visualization
where you added it. During execution, the connection
creates a new resource on the FHIR server.
The connection returns a MethodOutcome resource that includes
an id.idPart
field. This field contains the new resource’s
resource ID, which you might want to map to a
subsequent step in the flow.
If this flow needs additional steps to obtain the data that you want the new resource to contain, add them before this FHIR connection. After those steps are in place, add a data mapper step to the flow just before the FHIR connection that creates a new resource. In the data mapper step, map to the fields in the resource to be created.
| Without a data mapper step just before a FHIR connection that creates a new resource, the connection tries to create an empty resource. Depending on the FHIR server configuration, this might or might not work. |
Updating all fields in a resource on a FHIR server
In an integration, you can update a resource that is on a FHIR server. To provide the updated values, add a data mapper step to the flow just before a FHIR connection that updates a resource. It is expected that previous steps in the flow provide the data that you want the updated resource to contain. Map fields in the previous steps to fields in the target resource that this FHIR connection updates.
| The updated resource contains only the fields that you map to. In other words, in addition to mapping the fields whose values are changing, you must map the fields that you want to be in the resource and whose values are not changing. If you do not map a particular resource field then the connection deletes that field from the updated resource. |
Be sure to map the resource ID from a previous step to the resource ID in this connection. This is the only resource field that the connection does not change. If the FHIR server does not already have a resource that has the resource ID for the resource to be updated, then the connection creates a new resource with that resource ID. This is the only way to add a new resource that has a resource ID that you choose.
To update or create a resource, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.
-
You created a connection to the FHIR server on which you want to update or create a resource.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to add a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FHIR connection that you want to use to update a resource on a FHIR server.
-
On the Choose an action page, select Update.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to update or create.
-
In the Contained Resource Types field, if the resource type that you want to update or create contains other resource types, select them. Use the Ctrl key if you need to select more than one.
Identifying contained resource types lets the data mapper display the fields that are in the contained resources. If you do not specify a contained resource type then you cannot map to or from any fields that are in the contained resource. There is no harm in selecting a resource that is not actually contained.
-
Click Next to add this connection to the flow.
-
If this flow needs additional steps to obtain the data that you want the updated resource to contain, add them before this FHIR connection.
-
In the integration visualization, click the plus sign that is before the FHIR connection that updates a resource.
-
Click Data Mapper.
-
In the data mapper:
-
Map a resource ID to the target resource ID. This is the only way to specify the resource ID for a new resource.
-
Map to each resource field that you want the updated or new resource to contain. Be sure to map fields whose values are not changing, as well as fields whose values need to be updated.
-
Click Done to add the data mapper step to the flow.
-
The connection appears in the integration visualization
where you added it. During execution, the connection
updates or creates a resource on the FHIR server and returns a
MethodOutcome resource that includes an id.idPart
field.
This field contains the updated/created resource’s ID,
which you might want to map
to a subsequent step in the flow.
Updating specified fields in a resource on a FHIR server
In an integration, you can update individual fields in a resource that is on a FHIR server. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a connection to the FHIR server that has the resource that you want to update.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to choose a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FHIR connection that you want to use to update the resource.
-
On the Choose an action page, select Patch.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of the resource whose fields you want to update.
-
In the Number of Operations field, specify the number of fields that you want to update.
-
Leave the Resource id field blank if you want to map the value from a previous step in the flow, which is typically what you want to do. Otherwise, specify the resource ID of the resource whose fields you want to update.
-
Specify a JSON patch that describes the updates. The JSON patch must have the format described in What is a JSON Patch?.
Examples of patches for a
Patient
resource:Set the
active
field totrue
:[{ "op":"replace", "path":"/active", "value": true }]
Replace the value of the
name
field, which is an array of the patient’s names. In this example, the patient has one name. If the patient had more than one name, a similarly formatted patch could replace all of the patient’s names:[{ "op":"replace", "path":"/name", "value": [{"given": ["Bob"]}] }]
Replace the given name of a patient:
[{ "op":"replace", "path":"/name/0/given/0", "value": "John" }]
Add another name to a patient before the first name:
[{ "op":"add", "path":"/name/0", "value": {"given": ["Anthony"]} }]
For some updates, you must specify the JSON patch when you configure the Patch action. For example, if you want to copy the value of a resource field to another field. For other updates, you can leave the JSON Patch field blank and instead map values that define each update.
-
Click Next to add this connection to the flow.
-
If you did not specify a JSON patch and/or a resource ID, then add a data mapper step:
-
In the flow visualization, click the plus sign that is before the FHIR connection that you just added.
-
Click Data Mapper.
The Target panel displays a numbered folder for each field that you want to update. When you configured the Patch action, you specified how many fields to update. The data mapper displays this number of folders in the Target panel. For example, if you specified 3 as the number of fields to update, you would see three target folders with the labels
1
,2
, and3
. -
For each field that you want to update, map to the fields in one target folder:
-
In the Target panel, expand a folder to display three fields for
op
,path
, andvalue
. -
Map a source field, constant, or property to the target
path
field. The path identifies the resource field that you want to update. In a path value, a number indicates the index of a list field, and a slash leads to a child field. For example, map this path/name/1/given/1/value
to update the value of the given name field. -
Accept the default update operation, which replaces the current value of the field, or map a source field, constant, or property to the
op
field to indicate how you want to update the field. For details about possible operations, see JSON patch operations. -
If you are updating a field to have a new value, then map a source field, constant, or property to the target
value
. This is the new value that you want the field to contain.
-
-
If you did not specify a resource ID when you configured the Patch action, then map the resource ID to the target id field.
-
Click Done to add the data mapper step to the flow.
-
The connection appears in the integration visualization
where you added it. During execution,
the connection updates the specified resource field(s)
and returns a MethodOutcome resource that includes
an id.idPart
field. This field contains
the ID of the resource that was updated.
Creating resources of different types on a FHIR server
In an integration, you can create two or more resources on a FHIR server and each resource can be of a different type. For example, you can add a new patient resource and a new provider resource in one connection to a FHIR server. To do this, add a FHIR connection to the middle of a flow, or as a simple integration’s finish connection.
-
You created a connection to the FHIR server that you want to add resources to.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to choose a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FHIR connection that you want to use to create and add new resources to a FHIR server.
-
On the Choose an action page, select Transaction.
-
In the Included Resource Types field, select the resource types that this connection creates. Use the Ctrl key to select multiple resource types. The connection creates one resource of each type that you select.
-
Click Next to add this connection to the flow.
-
To populate fields in the new resources, add a data mapper step before this connection:
-
In the flow visualization, click the plus sign that is before the connection that you just added.
-
Click Data Mapper.
-
In the data mapper, map source fields to the target resource fields. The new resources contain only the target fields that you map to.
-
Click Next to add the data mapper step to the flow.
-
The connection appears in the integration visualization where you added it. During execution, the connection adds all resources to the FHIR server or, if there is an error, the connection does not add any resources to the FHIR server. A successful action returns a transaction resource, which contains the resource ID for each new resource. You can map these resource IDs to subsequent steps in the flow.
Deleting a resource from a FHIR server
In an integration, you can delete a resource from a FHIR server. To do this, add a FHIR connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a connection to the FHIR server that has the resource that you want to delete.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to select a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FHIR connection that you want to use to delete the resource.
-
On the Choose an action page, select Delete.
-
Click in the Resource Type field to display a list of FHIR resource types. Select or enter the type of resource that you want to delete.
-
In the Resource Id field, specify the resource ID of the resource that you want to delete or leave this field blank if you plan to map the resource ID from an earlier step in the integration.
-
In the Resource version field, optionally specify a version ID for the resource. Leave this field blank to delete the most recent version of the resource or to map the version ID of the resource that you want to delete from a previous step.
-
Click Next to add this connection to the flow. .
The connection appears in the integration visualization
where you added it. During execution, the connection
deletes the specified resource on the FHIR server and returns a
MethodOutcome resource that includes an id.idPart
field.
This field contains the resource ID for the deleted resource.
To map a value to the Resource Id field or the Resource version field, add a data mapper step before this connection.
Connecting to an FTP or SFTP server
In an integration, you can connect to an FTP or SFTP server to download or upload files. To do this, create an FTP or SFTP connection and then add it to an integration flow. The following topics provide details:
Creating an FTP or SFTP connection
In an integration, to download or upload files from/to an FTP or SFTP server, create a connection to that FTP or SFTP server. You can add the same connection to any number of integrations.
You must know the host name of the server you want to connect to.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
To create a connection that uses File Transfer Protocol, click the FTP connector.
Or, to create a connection that uses Secure File Transfer Protocol, click the SFTP connector.
-
Configure the connection.
-
For an FTP connection:
-
Host is the only parameter that you must specify. Enter the host name of the server that you want to connect to. For example, if the name of your FTP host is
FTP.WEST
, then you would enter exactly that,FTP.WEST
. Do not specify the protocol, for example, you should not specify something like this:ftp://FTP.WEST
. -
Port is required and has a default value of
21
. This is the port that the FTP server is listening on. -
All other parameters are either not required or have default values. The defaults are suitable for most integrations. Descriptions of these parameters are after this procedure.
-
-
For an SFTP connection, there must be values for these parameters:
-
Host is the host name of the SFTP server that you want to connect to. For example, if the name of your SFTP host is
SFTP.EAST
, then you would enter exactly that,SFTP.EAST
. Do not specify the protocol, for example, you should not specify something like this:sftp://SFTP.EAST
. -
Port has a default of
22
. This is the port that the SFTP server is listening on. -
User name of the account that you want to use to access the SFTP server.
-
Password that is associated with that user name.
-
All other parameters have default values. The defaults are suitable for most integrations. Descriptions of these parameters are after this procedure.
-
-
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether or not validation is successful. If validation fails, revise the configuration details as needed and try again.
-
When validation is successful, click Next.
-
In the Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
XLight FTP Server
. -
In the Description field, optionally enter any information that is helpful to know about this connection.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that XLight FTP Server appears as a connection that you can choose to add to an integration.
-
Connect timeout defaults to 10000 milliseconds and indicates a maximum wait of 10 seconds to establish the connection. If 10 seconds elapse without a connection then Syndesis waits for the number of milliseconds defined by Reconnect delay and then tries to reconnect.
-
Reconnect delay defaults to 1000 milliseconds and indicates the wait time before trying to reconnect again.
-
Maximum reconnect attempts defaults to 3. Syndesis tries as many as 3 times to establish a connection.
-
Binary file transfer mode is used by default. Select No for ASCII transfer mode.
-
Passive connection mode defaults to Yes, which is usually the preferred mode. In passive mode, the client opens communication channels with the server as a way to avoid firewall issues. If you select No then active mode is used.
-
Disconnect from the server after use defaults to No. The connection remains established after it performs the action. Select Yes if you want to disconnect from the server after the connection performs the upload or download.
-
Data timeout defaults to 30000 milliseconds and indicates the maximum length of time that Syndesis waits for a reply.
Obtaining files from an FTP or SFTP server
To trigger integration execution when an FTP or SFTP connection finds the file(s) you are interested in, add an FTP or SFTP connection as an integration’s start connection.
You created an FTP or SFTP connection.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the FTP or SFTP connection that you want to use to poll an FTP or SFTP server.
-
On the Choose an action page, select Download.
-
In the File name expression field, if you are interested in a single file, then enter an Apache Camel Simple language expression that resolves to a file name. You cannot specify a regular expression. The connection polls (periodically checks) the server for this file and downloads it when it is found. Leave this field blank if you want to download more than one file.
-
In the FTP directory field, enter the absolute or relative path of the server directory to poll. The connection watches this directory for any content and downloads all files when it finds any content.
-
In the Milliseconds before polling starts field, accept the default of 1000 milliseconds or change the number of milliseconds.
-
In the Milliseconds before the next poll field, accept the default of 500 milliseconds or change the number of milliseconds. This is the interval between polls.
-
In the Delete after download field, accept the default of No or select Yes to download the file(s) and then delete it(them) from the server.
-
Click Next to specify the action’s output type.
-
In the Select Type field, if the data type does not need to be known, accept Type specification not required and click Next. You do not need to follow the rest of these instructions.
However, a structured data type is recommended. For example, if you want to map the connection output in a data mapper step then you must specify the data type. The data mapper cannot display fields for unstructured data.
To specify the data type, click in the Select Type field and select one of the following as the schema type:
-
JSON schema is a document that describes the structure of JSON data. The document’s media type is
application/schema+json
. -
JSON instance is a document that contains JSON data. The document’s media type is
application/json
. -
XML schema is a document that describes the structure of XML data. The document’s file extension is
.xsd
. -
XML instance is a document that contains XML data. The document’s file extension is
.xml
.
-
-
In the Definition input box, paste a definition that conforms to the schema type you selected. For example, if you select JSON schema then you would paste the content of a JSON schema file, which has a media type of
application/schema+json
. -
In the Data Type Name field, enter a name that you choose for the data type. For example, if you are specifying a JSON schema for vendors then you might specify
Vendor
as the data type name.You will see this data type name when you are creating or editing an integration that uses the connection for which you are specifying this type. Syndesis displays the type name in the integration visualization and in the data mapper.
-
In the Data Type Description field, provide information that helps you distinguish this type. This description appears in the data mapper when you hover over the step that processes this type.
-
Click Next.
The connection appears at the beginning of the integration visualization.
Uploading files to an FTP or SFTP server
In an integration, you can upload files to an FTP or SFTP server in the middle of a flow or to finish a simple integration. To do this, add an FTP or SFTP connection to the middle of a flow or as a simple integration’s finish connection.
-
You created an FTP or SFTP connection.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you to choose a finish connection.
-
On the Add to Integration page, click the plus sign where you want to add the connection. Skip this step if Syndesis is prompting you to choose the finish connection.
-
Click the FTP or SFTP connection that you want to use to upload files.
-