On the Choose an action page, select Upload.
-
In the File name expression field, if you want to upload only one particular file, then enter an Apache Camel Simple language expression that resolves to a file name. This is the name of the file that the action uploads to the server. You cannot specify a regular expression. To upload more than one file, leave this field blank.
-
In the FTP directory field, enter the absolute or relative name of a server directory. If the File name expression field contains an expression, then the connection stores the specified file in this directory. If the File name expression field is blank, then the connection uploads to this directory all files that were received from the previous step.
-
In the If file exists field, indicate the behavior when you are uploading a file that has the same path and name as a file that is on the server. Accept the default, Override, to overwrite the file that is on the server with the file that you are uploading. Or, select one of the following:
-
Append adds the content in the file being uploaded to the file that is on the server.
-
Fail throws
GenericFileOperationException
. The integration does not enter an error state. -
Ignore does not upload the file. The integration continues running under the assumption that everything is okay.
-
Move renames one of the files.
-
TryRename uploads the file with a temporary name and renames the file to the desired name. This operation does not check for the existence of a file with the desired name, which makes the operation faster on most servers than when existence checks are done.
-
-
In the Temporary file prefix while copying field, specify a string. The connection prepends this string to the name of a file while it is being uploaded. This enables the connection to write to a temporary file on the server and then rename that temporary file to have the correct name. This is useful for reducing locks when uploading very large files.
-
In the Temporary file name while copying field, specify a string. The connection renames a file being uploaded to have this name while it is being uploaded. This enables the connection to write to a temporary file on the server and then rename that temporary file to have the correct name. This is useful for reducing locks when uploading very large files.
-
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 integration visualization where you added it.
Connecting to Google applications
An integration can connect to these Google applications: Gmail, Calendar, Sheets. See the following topics for details:
Registering Syndesis as a Google client application
In an integration, to be able to connect to Gmail, Google Calendar, or Google Sheets, you must register your Syndesis environment as a Google client application. During registration, you enable Google APIs and create credentials that Syndesis uses to access the Google APIs that you have enabled.
With registration in place, you can create multiple connections to Gmail, Google Calendar, and Google Sheets. You can use each connection in multiple integrations. While each connection to a Google application can use the same Google client ID and Google client secret, which you obtain during registration, each connection can access a different Google account, which you choose.
This procedure instructs you to enable the Gmail API, the Google Calendar API, and the Google Sheets API. However, you can enable only the API(s) that you need rather than all three APIs. At a later time, if you need to create connections to the applications whose APIs you did not enable, you can return here and follow the instructions to enable their APIs.
|
You must create a new Google client application for Syndesis. The credentials that Google provides for a new client application contain a refresh token that is used for refreshing expired access tokens. This refresh token is available only the first time that the Syndesis client application uses the credentials. In Syndesis, connections to Gmail, Google Calendar, and Google Sheets can all use the same Google client ID and Google client secret. If they do, the refresh token is available to all connections to Google applications. When you view connection details in the Syndesis user interface, do not click the Validate button. Validation is a second use of the credentials and the refresh token is no longer part of the client credentials. You can, however, re-connect to Google applications. In development environments, be careful if you choose to use the Google client ID and Google client secret that you are using for some other, non-Syndesis, OAuth client. Syndesis requires offline access that is requested on the first OAuth exchange. If another OAuth client already entered the OAuth exchange and did not request offline access, then Syndesis cannot obtain offline access on subsequent OAuth exchanges. If you are unsure whether offline access was requested on the first exchange, create a new Google client application for Syndesis. |
-
You must be able to sign in to the Google account that you want to use to register Syndesis as a Google client application.
-
In Syndesis:
-
In the left navigation 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 later in this procedure.
-
-
In another browser tab, go to
https://console.developers.google.com
and do the following:-
Check that you are signed into the Google account that you want to use to register Syndesis as a Google client application. Or, choose a different Google account and sign in to that account.
The name of the current Google project appears at the top of the Google APIs page.
-
To use the current project to grant authorization to Syndesis, continue to the next step. To grant authorization to Syndesis in another Google project, choose or create that project. If this Google account does not already have a project, you must create one.
-
Enable Google APIs:
-
In the upper left corner, click and select APIs and Services > Library.
-
If necessary, scroll down to see the G Suite row of cards.
-
Click the Google Calendar API card, which displays a page that indicates that the Google Calendar API is enabled.
-
Scroll down and click the Gmail API card, which displays a page that indicates that the Gmail API is enabled.
-
In the upper left corner, click and select APIs and Services > Library.
-
If necessary, scroll down to see the G Suite row of cards.
-
Click the Google Sheets API card, which displays a page that indicates that the Google Sheets API is enabled.
-
-
Give your client application a name:
-
Click MANAGE.
-
In the page that appears, in the left navigation panel, click Credentials and then on the right, click Credentials in APIs & Services.
-
Click the OAuth consent screen tab.
-
In the page that appears, in the Application Name field, enter a name for the Syndesis client application. For example, enter
Syndesis client application
. -
Skip the other fields.
-
Click Save.
-
-
Obtain client application credentials as follows:
-
To the right of Create Credentials, click the down arrow to display a menu and select OAuth client ID.
-
In the page that appears, select Web application to display more content.
-
In the Name field, enter a name for the OAuth client ID for your Syndesis environment. This is different from the name that you entered for the client application itself. For example, enter
OAuth client ID for Syndesis
. -
Skip Authorized JavaScript origins.
-
In the Authorized redirect URIs field, paste the callback URL that you copied from your Syndesis environment at the beginning of this procedure.
-
Click Create to display the client ID and client secret for your Syndesis environment.
-
-
To the right of the client ID field, click to copy the client ID to your clipboard.
-
-
Return to the Syndesis Settings page and do the following:
-
Expand the entries for Gmail, Google Calendar, and Google Sheets.
-
In the Client ID field for each Google application, paste the Google client ID that you just copied.
-
-
Return to the Google developers site and to the right of the client secret field, click to copy the client secret to your clipboard.
-
Return to the Syndesis Settings page and do the following in the entry for each Google application:
-
In the Client Secret field, paste the Google client secret that you just copied.
-
Click Save. You should get a Registration Successful! notification.
-
Collapse the entry.
-
For each Google application API that you enabled, you can create a connection to that application.
All connections from Syndesis to Google applications use the same Google client ID and Google client secret.
|
The Google client ID and Google client secret contain token refresh information to ensure that integrations that have connections to Google applications continuously work correctly. Consequently, you should not obtain new credentials. If you do, then you would need to recreate each Google connection, replace the old connections with new connections, and re-publish each integration that uses a Google connection. |
Connecting to Gmail
To trigger execution of an integration when a particular Gmail account receives an email, add a Gmail connection to a simple integration as its start connection. In an integration, to send an email from a particular Gmail account, do either of the following:
-
Add a Gmail connection to the middle of a flow.
-
Add a Gmail connection to finish a simple integration.
The general steps for connecting to Gmail in an integration are:
-
Creating a Gmail connection. When you do this you choose the Gmail account that the connection is authorized to access.
-
If your integration sends an email from a Gmail account, decide how to populate an email to send.
-
Adding a Gmail connection to an integration flow.
-
For a Gmail connection that sends an email, optionally mapping integration data to the email fields.
Information and instructions are in the following topics:
Creating a Gmail connection
When you create a Gmail connection, you authorize the connection to access one particular Gmail account. After you create a Gmail connection, you can add it to multiple integrations.
-
You registered Syndesis as a Google client application and enabled the Gmail API.
-
The Syndesis Settings page entry for Gmail has values for the client ID and client secret, which you obtained by registering Syndesis as a Google client application.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
-
Click the Gmail connector.
-
In the Configure Connection page, click Connect Gmail, which takes you to a Sign in with Gmail page.
If Connect Gmail does not display, your Syndesis environment is not registered as a Google client application. See Registering Syndesis as a Google client application. When you try to create a Gmail connection and your Syndesis environment is not registered as a Google client application, then Syndesis displays multiple fields that prompt for authorization information. While you can create a Gmail connection by entering values in these fields, it is not recommended.
-
In the page that is prompting you to sign in to Gmail, enter the email address of the Google account that you want this connection to access from Syndesis and click Next.
-
In response to openshiftapps.com wants to access your Google Account, click Allow to return to Syndesis.
-
In the Syndesis Name field, enter your choice of a name that helps you distinguish this connection from any other connections. For example, enter
Gmail Connect 1
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Gmail connection that uses jkim Gmail account credentials.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Gmail Connect 1 appears as a connection that you can choose to add to an integration.
Alternatives for populating email to send
A Gmail connection that finishes a simple integration or that is in the middle of a flow sends an email from the Gmail account that the connection is authorized to access. There are several ways to populate the content of the email that the connection sends. Before you add a Gmail connection that sends an email, consider how you want to populate that email.
The alternatives for populating an email to send are as follows:
-
Add a data mapper step just before the Gmail connection that sends an email. In this data mapper step, map data fields that are output from previous steps to Gmail connection Send Email action fields. The Send Email action fields are:
-
Email to
-
Email subject
-
Email text
-
Email cc
-
Email bcc
If you add a data mapper step then you can map one, some, or all Send Email action fields.
-
-
When you add a Gmail connection to a flow, configure the action by specifying values in the Send Email action fields. You can specify values in one, some, or all fields.
-
Use both a data mapper step and Send Email action configuration to populate the fields. In other words, you can configure the Send Email action by specifying one or more fields and also add a data mapper step that populates other fields.
A value that you specify directly in a Send Email action field has precedence over a value that is mapped to the Send Email action field. In other words, suppose you populate a Send Email field by specifying a value when you add the connection and configure the action and also by mapping a value to the same field. The value that you specify in the action configuration always overrides the value that was mapped. For example, suppose you specify
<EMAIL_ADDRESS>in the Email to action field and you also map an email field from a previous step to the Gmail Email to field. The integration always<EMAIL_ADDRESS>as the email address.
When you add a Gmail connection that sends an email, all action configuration parameters are optional. This is because you might choose to populate an email entirely by mapping integration data to the Send Email action fields. However, the presence of an email address in the Email to field, either by action configuration specification or by mapping, is required. Without an email address to send the message to, Syndesis generates a runtime error and the integration stops executing.
Triggering an integration when polling returns a Gmail message
To trigger execution of an integration based on email received by a particular Gmail account, add a Gmail connection as the start connection of a simple integration. When the integration is running, the Gmail connection checks this account for emails at intervals that you control. When the connection finds an unread email, it passes the email to the next step in the integration and, by default, marks the email as read.
-
You created a Gmail connection that is authorized to access the Gmail account that you want to obtain emails from.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Gmail connection that you want to use to start the integration.
-
On the Choose an action page, select the Receive Email action.
-
To configure the Receive Email action:
-
In the Delay field, accept the default of 30 seconds or specify how often you want the integration to check for new email.
-
Leave the Labels field blank to obtain any unread email. To obtain only certain emails, specify a comma-separated list of labels that are used in the Gmail account that the connection is accessing. By default, the integration obtains the unread emails that have those labels.
-
Select Mark as read to ensure that the connection does not return the same email twice. If Mark as read is not selected, the connection returns emails that are in the account’s in box, whether or not they were previously read. Or, if you specify one or more labels, then the integration return emails that have those labels whether or not they were already read.
-
In the Max Results field, accept the default of 5 or indicate the maximum number of emails that the connection can return for each poll. If the connection finds more than this number of unread emails, then it returns the most recent Max Results emails.
When a Gmail connection returns more than one email, the integration processes the emails as a batch. In other words, Syndesis executes the integration once for the batch.
-
Click Next to add this Gmail connection as the start connection in the integration. The connection appears as the first step in the integration flow.
-
Sending an email from a Gmail account
In an integration, you can send an email from a Gmail account either in the middle of a flow or to finish a simple integration. To do this, add a Gmail connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a Gmail connection.
-
You are familiar with the alternatives for populating an email to send and you have a plan for populating such emails.
-
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 Gmail connection that you want to use to send an email.
-
On the Choose an action page, select Send Email.
-
On the Configure Send Email page, do one of the following:
-
Leave all fields blank if you plan to add a data mapper step just before this connection and you plan to map integration data to the Send Email fields.
-
Enter information in one or more of the following Send Email fields. Separate multiple email addresses with a comma.
-
Email To
-
Email Subject
-
Email Text
-
Email cc
-
Email bcc
-
-
Leave some fields blank and enter information in some fields.
If you plan to add a data mapper step just before this Gmail connection, and you want to map integration data to some email fields, leave those fields blank in the action configuration. Enter values in other action fields as needed.
A value that you specify in a Send Email action configuration field has precedence over a value that is mapped from a previous step.
-
-
Click Next to add the connection to the flow.
The connection appears in the integration flow where you added it.
If you plan to add a data mapper step before this connection, first add any other connections that you plan to add to this flow. Then add the data mapper step.
Connecting to Google Calendar
To trigger integration execution when a poll returns an update to a Google calendar, add a Google Calendar connection to a simple integration as its start connection. To add an event to a calendar or update an event in a calendar, you can do either of the following:
-
Add a Google Calendar connection to the middle of a flow.
-
Add a Google Calendar connection to finish a simple integration.
Details for connecting to Google Calendar are in the following topics:
Creating a Google Calendar connection
When you create a Google Calendar connection, you authorize the connection to access the Google Calendars that are associated with one particular Google account. After you create a Google Calendar connection, you can add it to multiple integrations.
-
You registered Syndesis as a Google client application and enabled the Google Calendar API.
-
The Syndesis Settings page entry for Google Calendar has values for the client ID and client secret, which you obtained by registering Syndesis as a Google client application.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
-
Click the Google Calendar connector.
-
In the Configure Connection page, click Connect Google Calendar, which takes you to a Google sign-in page.
If Connect Google Calendar does not display, then your Syndesis environment is not registered as a Google client application with the Google Calendar API enabled. See Registering Syndesis as a Google client application. When your environment is not registered with Google, then when you try to create a Google Calendar connection, Syndesis displays multiple fields that prompt for authorization information. While you can create a Google Calendar connection by entering values in these fields, it is not recommended.
-
In the Google sign-in page, select the Google account that you want this connection to access from Syndesis and click Next.
-
In response to the openshiftapps.com wants to access your Google Account prompt, click Allow to return to Syndesis.
-
In the Syndesis Name field, enter your choice of a name that helps you distinguish this connection from other connections. For example, enter
Google Calendar Work Connection
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Google Calendar connection that uses my Google work account.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Google Calendar Work Connection appears as a connection that you can choose to add to an integration.
Triggering an integration when polling returns an event from a Google Calendar
To trigger execution of an integration upon obtaining events from a Google Calendar that you specify, add a Google Calendar connection to a simple integration as its start connection. When the integration is running, the Google Calendar connection checks the Google Calendar for events at intervals that you control. When the connection finds events that comply with the way that you configured the Google Calendar Get Events action, the connection passes the events to the next step in the integration.
When a Google Calendar connection returns more than one event, Syndesis executes the integration for each returned event. For example, if the poll returns 5 events then Syndesis executes the integration five times.
-
You created a Google Calendar connection.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Google Calendar connection that you want to use to start the integration.
-
On the Choose an action page, select the Get Events action.
-
To configure the Get Events action:
-
In the Delay field, accept the default of 30 seconds or specify how often you want the integration to check the calendar.
-
In the Calendar name field, enter the name of a calendar that is accessible from the Google account that this Google Calendar connection is authorized to access.
-
In the Max Results field, accept the default of 5 or indicate the maximum number of events that the connection can return for each poll.
-
Select one of the following to indicate the date that you want the connection to use to start checking for events. The connection checks that date and subsequent dates.
-
Consume from the current date ahead starts on the current date.
For example, if you select this option, and if Max Results is 5, then the Google Calendar connection starts checking for events on the current date and returns no more than the first five events that it finds. It does not matter whether or not these events have been updated or added since the last poll.
-
Consume from the last event update date on the next poll starts on the date of the most recently updated event that was returned in a previous poll.
For example, if you select this option, and if Max Results is 5, then the Google Calendar connection returns no more that 5 updated or new events. The connection starts checking for new or updated events on the date of the most recently updated event that was returned in a previous poll.
-
-
Optionally, in the Query for events field, specify text to filter the events that the poll can return. The connection returns only events that contain the specified text in at least one event field.
For example, suppose that you specify
Standup meeting
in the query field. A poll would return only those events that haveStandup meeting
in an event field.
-
-
Click Next to add this Google Calendar connection as the integration’s start connection.
The connection appears as the first step in the simple integration.
Obtaining a particular event from a Google Calendar
In an integration, you can obtain a particular Google Calendar event in the middle of a flow. Obtaining a particular event is useful, for example, when you want to:
-
Update the event in a subsequent Google Calendar connection.
-
Announce the event by using a subsequent Twitter connection.
To obtain one event, add a Google Calendar connection to the middle of a flow.
|
In this release, while obtaining a specific event in a simple integration’s finish connection is supported, it is not particularly useful. This is expected to change in a future release. |
-
You created a Google Calendar connection that is authorized to access the Google Calendar that has the event that that you want to get.
-
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 a Google Calendar connection that is authorized to access the calendar that you want to connect to.
-
On the Choose an action page, select Get a Specific Event.
-
Specify the name of the calendar that has the event that you want.
-
Specify the ID of the event to get. To obtain the event ID, do one of the following:
-
Map it from a previous Google Calendar connection.
-
Manually obtain it from the calendar as follows:
-
In a browser, display the calendar that contains the event you want to get.
-
Append
?gsessionid=OK&eventdeb=1
to the URL and redisplay the calendar. -
In the calendar, click the event that you want to get.
-
In the event popup, click and select Troubleshooting info.
-
In the popup that Google Calendar displays, copy the string that follows
eid=
. For example, an event ID looks something like this:p1pva2a4t504gbsha12di9ch6k_20181107T150000Z*
.
-
-
-
Click Next to add the connection to the flow.
The connection appears in the flow where you added it.
If you want to map any values from a previous step to the fields in this connection, add a data mapper step. First, add all needed connections to the flow. Then add a data mapper step immediately before this connection.
Adding an event to a Google Calendar
In an integration, you can add an event to a Google Calendar in the middle of a flow or to finish a simple integration. To do this, add a Google Calendar connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a Google Calendar connection that is authorized to access the Google Calendar to which you want to add an event.
-
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 a Google Calendar connection that is authorized to access the calendar that you want to add an event to.
-
On the Choose an action page, select the Create Event action.
-
Configure the Create Event action:
-
Enter a title for the new event.
-
Enter the name of the Google Calendar to add the event to.
-
For the other input parameters, you can enter data or you might want to map values from an event that you obtained in a previous Google Calendar connection.
-
-
Click Next to add the connection to the flow.
The connection appears in the integration flow where you added it.
If you want to map any values to the fields in this Google Calendar connection, add a data mapper step to the flow. First, add all needed connections to the flow. Then add a data mapper step immediately before this Google Calendar connection.
Updating an event in a Google Calendar
In an integration, you can update an event in a Google Calendar in the middle of a flow or to finish a simple integration. To do this, add a Google Calendar connection to the middle of a flow or as a simple integration’s finish connection.
|
In this release, the Update Event action requires a value in each event field. In most if not all cases, this means that you must add a Google Calendar connection that obtains the event that you want to update, then add the Google Calendar connection that updates the event, and then insert a data mapper step between the two Google Calendar connections. |
-
You created a Google Calendar connection that is authorized to access the Google Calendar that has the event that you want to update.
-
In the flow, there is an earlier connection to Google Calendar and that connection obtains the event 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 a Google Calendar connection that is authorized to access the calendar that has the event that you want to update.
-
On the Choose an action page, select Update Event.
-
To configure the Update Event action:
-
Enter the title of the event that you want to update.
-
Enter content in each event field that you want to update. Do not enter content in an event field when you want the content in that field to remain unchanged.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
-
In the integration visualization, click the plus sign that is just before the connection that you just added.
-
Click Data Mapper.
-
In the data mapper, for each event field that remains the same in the updated event, map that field from the Google Calendar connection that obtained the event to the corresponding field in the Google Calendar connection that updates the event.
Do not map fields that you are updating. If you map a field and also specify an update for that field when you configure the Update Event action, Syndesis uses the mapped value.
-
In the upper right, click Done to add the data mapper step.
Connecting to Google Sheets
To trigger execution of an integration when a Google Sheets connection returns spreadsheet data or spreadsheet properties, add a Google Sheets connection to a simple integration as its start connection. To finish a simple integration by updating spreadsheet values or properties, or by inserting a chart or pivot table into a spreadsheet, add a Google Sheets connection to a simple integration as its finish connection.
In the middle of a flow, you can add a Google Sheets connection that obtains, creates or updates values in a spreadsheet, or that inserts a chart or pivot table into a spreadsheet.
Details for connecting to Google Sheets are in the following topics:
Creating a Google Sheets connection
When you create a Google Sheets connection, you authorize the connection to access the Google Sheets spreadsheets that are associated with one particular Google account, which you choose. After you create a Google Sheets connection, you can add it to multiple integrations.
-
You registered Syndesis as a Google client application and enabled the Google Sheets API.
-
The Syndesis Settings page entry for Google Sheets has values for the client ID and client secret, which you obtained by registering Syndesis as a Google client application.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display the available connectors. A connector is a template that you use to create one or more connections.
-
Click the Google Sheets connector.
-
In the Configure Connection page, click Connect Google Sheets, which takes you to a Google sign-in page.
If Connect Google Sheets does not display, then your Syndesis environment is not registered as a Google client application with the Google Sheets API enabled. See Registering Syndesis as a Google client application. When your environment is not registered with Google, then when you try to create a Google Sheets connection, Syndesis displays multiple fields that prompt for authorization information. While you can create a Google Sheets connection by entering values in these fields, it is not recommended.
-
In the Google sign-in page, select the Google account that you want this connection to access from Syndesis and click Next.
-
In response to the openshiftapps.com wants to access your Google Account prompt, click Allow to return to Syndesis.
-
In the Syndesis Name field, enter your choice of a name that helps you distinguish this connection from other connections. For example, enter
Google Sheets Work Connection
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Google Sheets connection that uses my Google work account.
-
Click Save to see that the connection that you created is now available. If you entered the example name, you would see that Google Sheets Work Connection appears as a connection that you can choose to add to an integration.
Obtaining spreadsheet data to trigger an integration or in the middle of a flow
To trigger execution of an integration upon obtaining data from a Google Sheets spreadsheet, add a Google Sheets connection to a simple integration as its start connection. When the integration is running, the Google Sheets connection polls the spreadsheet at the interval that you specified, obtains the data that you identified, and passes the data to the next step in the integration.
To obtain spreadsheet data in the middle of a flow, add a Google Sheets connection as a middle connection. During execution, Syndesis polls the spreadsheet for the specified data as soon as it starts processing this connection. In other words, the connection does not wait for an interval to elapse before polling the spreadsheet.
To obtain data from a particular sheet in a spreadsheet, you specify the sheet name when you configure the action for the Google Sheets connection. A particular connection can obtain data from only one sheet.
Between polls, if there are no changes to the sheet values that the connection is configured to return, then the next poll returns the same values as the previous poll.
-
You created a Google Sheets connection that is authorized to access the spreadsheet that you want to obtain data from.
-
If this Google Sheets connection is triggering integration execution, then you are creating an integration and Syndesis is prompting you to choose the start connection.
-
If this Google Sheets connection is in the middle of a flow, then the integration already has a start connection and a finish connection, and Syndesis is prompting you to add to the integration by choosing a step.
-
Click the Google Sheets connection that you want to use.
-
On the Choose an action page, for a start connection, select the Get sheet values action or for a middle connection, select the Retrieve sheet values action.
-
To configure the action:
-
In the SpreadsheetId field, enter the ID of a Google spreadsheet that is accessible from the Google account that this Google Sheets connection is authorized to access.
To obtain a spreadsheet ID, display the spreadsheet in a browser. The ID is the part of the URL between
d/
and/edit
. -
In the Range field, enter Google A1 notation that identifies the data that you want to obtain. The default is A:A.
For example, suppose that you want all data from a spreadsheet that has one sheet with 4 columns. Specify
A:D
. Or, to obtain data from rows 5 through 15, specifyA5:D15
.If the spreadsheet from which you are obtaining data has more than one sheet, specify the sheet name as well as the start cell coordinate and the end cell coordinate. If there is more than one sheet, and you do not specify a sheet name, then the connection obtains data from the first sheet in the spreadsheet. For example, specification of
2019!A1:D5
specifies that you want to obtain data from the sheet whose name is2019
. In that sheet, you want the data that is in columns A through D for rows 1 through 5. -
In the Major dimension field, accept Rows, which is the default, or select Columns.
Rows configures the action to return a collection of row objects where each row object contains a value for each desired column. When Major dimension is Rows, Syndesis can display meaningful column headings as field names in the data mapper, rather than A, B, C, and so on.
Columns configures the action to return a collection of column objects where each column object contains a value for each desired row.
-
In the Header row number field, if Major dimension is set to Rows, optionally enter the number of the row that contains the column headings in the data that the connection obtains. Specification of a header row enables Syndesis to obtain the headings from the spreadsheet. If you do not specify a header row, column headings default to a letter heading for each column in the range of data that the connection obtains. You can edit obtained headings or letter headings in the subsequent page.
If you are configuring a Google Sheets middle connection, the rest of the configuration options are not needed and Syndesis does not prompt for them. Skip to step 4. -
In the Split results field, accept No, which is the default, or select Yes. A setting of No configures the action to return data as a collection of values. That is, the connection passes a collection of row objects or a collection of column objects to the next step in the flow. Select Yes to enable the connection to split the returned data according to the setting of Major dimension. For example, if Major dimension is set to Rows then the connection returns row objects. Each row object triggers a separate execution of the flow. That is, Syndesis executes the flow once for each returned row object. For example, if the poll returns 5 rows then Syndesis executes the flow 5 times.
Syndesis also provides discrete split and aggregate steps, which you can add to a flow. If you want to process individual objects in one or more steps and then aggregate the row or column objects, do not split the Google Sheets connection result. Instead, accept the default, No, and then add a split step to the flow after this connection. A split step is required if you want an aggregate step in the flow.
-
In the Delay field, accept the default of 30 seconds or specify how often you want the connection to obtain spreadsheet data.
-
In the Max results field, accept the default of 0 if you do not want to restrict how many rows or columns polling can return. The setting of Max results applies to the setting of the major dimension in the result matrix. To limit the data that the connection returns for the major dimension, specify an integer.
For example, suppose that the major dimension is rows and that Max results is set to 25. The poll returns no more than 25 rows of values.
When Range specifies the major dimension and you also specify Max results, polling uses the lower number to determine how much data to return. Consequently, setting a value for Max results is more helpful when you specify only the minor dimension for Range. For example, consider a sheet that has 30 rows with three columns of values in each row. Suppose that Major dimension is Rows and Range is A:C. If you set Max results to 10, polling returns 10 rows of data. If you accept 0 as the setting of Max results, polling returns 30 rows. However, if you specify Range as A1:C15 and you also specify Max results as 25, polling returns 15 rows. If you specify Range as A1:C30 and you also specify Max results as 25, polling returns 25 rows.
-
-
Click Next to view the column names in the data that the connection obtains when Major dimension is set to Rows. If Major dimension is Columns, content in this field is ignored and you can click Next now to complete this procedure.
The values that appear in the Column names field become the field names that a data mapper step displays. If you specified a header row number, Syndesis displays the headings from that row in the sheet that you are obtaining data from. If you left the header row number field blank, Syndesis displays a letter (A, B, C, and so on) for each column in the range of data that you are obtaining.
-
Optionally, edit the Column names field so it contains the field names that you want to see in a data mapper step. The field must contain a comma-separated list with no spaces, for example,
Name,Address,City,State,Zip
. -
Click Next to add this Google Sheets connection to the flow.
If you added a Google Sheets connection as a start connection, Syndesis prompts you to add the integration’s finish connection. With the start and finish connections in the integration, add any other connections that you want in the integration.
After the connection that obtains sheet values, add a data mapper step. In the data mapper, Syndesis displays source fields according to how you configure the action that obtains spreadsheet values. That is, if the major dimension is Rows, then the data mapper lists the column names as fields that you can map to the target. If the major dimension is Columns, then the data mapper lists row indexes as fields that you can map to the target.
Google A1 notation for specifying groups of cells in a spreadsheet
Triggering an integration when polling returns spreadsheet properties
To trigger execution of an integration upon obtaining properties from a Google Sheets spreadsheet, add a Google Sheets connection to a simple integration as its start connection. When the integration is running, the Google Sheets connection polls the spreadsheet at the interval that you specified, obtains the spreadsheet properties, and passes the result to the next step in the integration.
Properties include the spreadsheet’s title, locale, and time zone. Between polls, if there are no changes to the sheet properties, then the next poll returns the same values as the previous poll.
-
You created a Google Sheets connection that is authorized to access the spreadsheet that you want to obtain properties from.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Google Sheets connection that you want to use to start the integration.
-
On the Choose an action page, select the Get spreadsheet properties action.
-
To configure the Get spreadsheet properties action:
-
In the SpreadsheetId field, enter the ID of a Google spreadsheet that is accessible from the Google account that this Google Sheets connection is authorized to access.
To obtain a spreadsheet ID, display the spreadsheet in a browser. The ID is the part of the URL between
d/
and/edit
. -
In the Delay field, accept the default of 30 seconds or specify how often you want the connection to obtain properties.
-
-
Click Next to add this Google Sheets connection as the integration’s start connection.
The integration now has a start connection and Syndesis is prompting you to choose the integration’s finish connection.
Creating a spreadsheet
To create a new spreadsheet in the middle of a flow, add a Google Sheets connection between the start and finish connections. While you can also finish a simple integration with a Google Sheets connection that creates a spreadsheet, you cannot add data to a new spreadsheet in the same connection. Therefore, when you want to create a spreadsheet and add data to the spreadsheet in the same flow, the flow requires two Google Sheets connections. One connection creates the spreadsheet and then a subsequent connection adds data to the spreadsheet.
-
You created a Google Sheets connection that is authorized to access the Google account in which you want to create the spreadsheet.
-
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 a Google Sheets connection that is authorized to access the Google account that you want to use to create the spreadsheet.
-
On the Choose an action page, select Create spreadsheet.
-
To configure the Create spreadsheet action:
-
In the Title field, enter the title of the new spreadsheet.
-
In the Time Zone field, enter the time zone that the new spreadsheet should use, for example,
India Standard Time
, orTokyo
. -
In the Locale field, enter the locale of the new spreadsheet, for example,
Canada
, orHong Kong
.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
A connection that creates a spreadsheet returns the spreadsheet ID for the new spreadsheet. In subsequent steps, you can map this spreadsheet ID to the spreadsheet ID in a connection that accesses the new spreadsheet, for example, to update it.
Updating data in a sheet
In an integration, you can update data in a spreadsheet in the middle of a flow or to finish a simple integration. To do this, add a Google Sheets connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a Google Sheets connection that is authorized to access the Google spreadsheet that you want to update.
-
You have access to the spreadsheet ID for the spreadsheet 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 a Google Sheets connection that is authorized to access the spreadsheet that you want to update.
-
On the Choose an action page, select Update sheet values.
-
To configure the Update sheet values action:
-
In the SpreadsheetId field, do one of the following:
-
Enter the ID of the spreadsheet that you want to update.
-
Leave the field blank. In this case, after you add this connection to the flow, you must add a data mapper step before this connection. In the data mapper step, map the spreadsheet ID from a previous connection to this connection. The previous connection must access the spreadsheet that you want to update in this connection.
-
-
In the Range field, use Google A1 notation to specify the spreadsheet cells that you want to update. Specify the start and end coordinates, for example,
A1:D4
updates the first 4 columns in the first 4 rows in the first sheet in the spreadsheet.The default is
A:A
, which updates the first column in the first sheet in the spreadsheet. -
In the Major dimension field, accept Rows, which is the default, or select Columns. Rows configures the action to use row objects to update the sheet. Each row object contains a value for each column that you want to update. Columns configures the action to use column objects to update the sheet. Each column object contains a value for each row that you want to update.
-
In the Value input option field, indicate how you want Google sheets to interpret the data that it receives for updating the sheet. Unspecified, which is the default, enables Google Sheets to automatically convert data that it recognizes. For example, if the input data is a date, then Google Sheets formats it as a date. If the input data is a decimal, then Google Sheets formats it as a decimal.
-
Unspecified defaults to the Google Sheets API setting, which defaults to User entered.
-
Raw causes Google Sheets to insert the input data as is.
-
User entered enables automatic conversion of recognizable data.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization in the location where you added it.
-
-
If you want to add any other connections to the flow, add them now and then return to these instructions.
-
After the flow has all desired connections, in the integration visualization, click the plus sign that is just before the Google Sheets connection that updates sheet values.
-
Click the Data Mapper card to add a data mapping step to the flow.
-
In the data mapper:
-
If you did not specify the spreadsheet ID when you configured the Update sheet values action, then map a source
spreadsheetId
to the targetspreadsheetId
. -
Specify the data that you want to use to update the sheet by mapping fields from a source step to the target spreadsheet. For example, you might map fields from another spreadsheet or from a database.
If you need to, you can edit the Google Sheets connection that updates sheet values and change the settings for Range or Major dimension. Changing these settings causes the data mapper to display different target fields according to your changes.
-
In the upper right, click Done to add the data mapper step.
-
Appending data to a sheet
You can append data to a sheet in the middle of a flow or to finish a simple integration. To do this, add a Google Sheets connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a Google Sheets connection that is authorized to access the Google spreadsheet in which you want to append data.
-
You have access to the ID for the spreadsheet in which you want to append data.
-
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 a Google Sheets connection that is authorized to access the spreadsheet in which you want to append data.
-
On the Choose an action page, select Append values to a sheet.
-
To configure the Append values to a sheet action:
-
In the SpreadsheetId field, do one of the following:
-
Enter the ID of the spreadsheet that you want to append values to.
-
Leave the field blank. In this case, after you add this connection to the flow, you must add a data mapper step before this connection. In the data mapper step, map the spreadsheet ID from a previous connection to this connection. The previous connection must access the spreadsheet that you want to append data to in this connection.
-
-
In the Range field, use Google A1 notation to specify the spreadsheet range that you want to append data to. Specify the start and end coordinates, for example,
A3:D3
appends data to the first sheet, after the third row for 4 columns. The default isA:A
, which appends data to the first column in the first sheet in the spreadsheet.The connection never overwrites data. The connection starts appending data after the range you specify, and then always appends data to the content that is in place.
-
In the Major dimension field, accept Rows, which is the default, or select Columns. Rows configures the action to use row objects to append data. Each row object contains a value for each column that you want to append data to. Columns configures the action to use column objects to append data. Each column object contains a value for each row that you want to append.
-
In the Value input option field, indicate how you want Google sheets to interpret the data that it receives for appending to a sheet. Unspecified, which is the default, enables Google Sheets to automatically convert data that it recognizes. For example, if the input data is a date, then Google Sheets formats it as a date. If the input data is a decimal, then Google Sheets formats it as a decimal.
-
Unspecified defaults to the Google Sheets API setting, which defaults to User entered.
-
Raw does nothing. Google Sheets inserts the input data as is.
-
User entered enables automatic conversion of recognizable data.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
The values that you specify to configure the Append values to a sheet action determine the fields that the data mapper displays for mapping to or from this connection.
-
-
If you want to add any other connections to the flow, add them now and then return to these instructions.
-
After the flow has all desired connections, in the integration visualization, click the plus sign that is just before the Google Sheets connection that appends data to a sheet.
-
Click Data Mapper to add a data mapping step to the flow.
-
In the data mapper:
-
If you did not specify the spreadsheet ID when you configured the Append values to a spreadsheet action, then map a source
spreadsheetId
to the targetspreadsheetId
. -
Specify the data to append to the sheet by mapping fields from a source step to the target spreadsheet. For example, you might map fields from another spreadsheet or from a database.
If you need to, you can edit the Google Sheets connection that appends sheet values and change the settings for Range or Major dimension. Changing these settings causes the data mapper to display different target fields according to your changes.
-
In the upper right, click Done to add the data mapper step.
-
Updating spreadsheet properties
In an integration, you can update the properties of a spreadsheet in the middle of a flow or to finish a simple integration. To do this, add a Google Sheets connection to the middle of a flow or as a simple integration’s finish connection.
Properties include the spreadsheet’s title, locale, and time zone.
When Syndesis prompts you to configure the Update spreadsheet properties action, you can leave some or all fields blank. If you leave a field blank, then in a data mapper step that is in the flow (you add it later) before this connection, you map fields from previous steps to blank Update spreadsheet properties action configuration fields.
-
You created a Google Sheets connection that is authorized to access the Google spreadsheet whose properties you want to update.
-
You have access to the spreadsheet ID for the spreadsheet whose properties 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 a Google Sheets connection that is authorized to access the spreadsheet whose properties you want to update.
-
On the Choose an action page, select Update spreadsheet properties.
-
To configure the Update spreadsheet properties action:
-
In the SpreadsheetId field, do one of the following:
-
Enter the ID of the spreadsheet whose properties you want to update.
-
Leave the field blank. In this case, after you add this connection to the flow, you must add a data mapper step that is before this connection. In the data mapper step, map the spreadsheet ID from a previous connection to this connection. The previous connection must access the spreadsheet that you want to update in this connection.
-
-
In the other fields, enter a value only if you want to change the property. Alternatively, you can leave the fields blank. If you do, then in a data mapper step that you add later, just before this connection, you can map the fields that you want to change.
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
-
-
If you want to add any other connections to the flow, add them now and then return to these instructions.
-
After the flow has all desired connections, you might want to use a data mapper step to update spreadsheet properties:
-
In the integration visualization, click the plus sign that is just before the Google Sheets connection that updates properties.
-
Click Data Mapper to add a data mapping step to the flow.
-
In the data mapper, if you did not specify a spreadsheet ID when you configured the Update spreadsheet properties action, map a source
spreadsheetId
to the targetspreadsheetId
. -
For each spreadsheet property that you want to change and for which you did not specify an updated value when you configured the Update spreadsheet properties action, map a field from a source step to the target spreadsheet property that you want to change.
-
In the upper right, click Done to add the data mapper step.
-
Adding a chart to a sheet
In the middle of a flow, or to finish a simple integration, you can add a basic chart or a pie chart to a Google Sheets spreadsheet. To do this, add a Google Sheets connection to the middle of a flow or as a simple integration’s finish connection. Then add a data mapper step just before the connection. In the data mapper step, set options that determine the location, properties, and content of the chart.
When Syndesis prompts you to configure the Add charts action, you can leave some or all fields blank. If you leave a field blank, you can map a value to that field in the data mapper step that you will add just before this connection.
-
You created a Google Sheets connection that is authorized to access the Google spreadsheet that you want to add a chart to.
-
You have access to the ID for the spreadsheet that you want to add a chart 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 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 a Google Sheets connection that is authorized to access the spreadsheet that you want to add a chart to.
-
On the Choose an action page, select Add charts.
-
To configure the Add charts action:
-
In the SpreadsheetId field, do one of the following:
-
Enter the ID of the spreadsheet that you want to add a chart to.
-
Leave the field blank. In the data mapper step that will be just before this connection, map the spreadsheet ID from a previous connection to this connection. The previous connection must access the spreadsheet that you want to add a chart to in this connection.
-
-
In the Chart Title field, enter a title.
Alternatively, leave the field blank. In the data mapper step that is just before this connection, map the chart title from a source field or property to the
title
target field. -
In the Subtitle field, enter a subtitle.
Alternatively, leave the field blank. In the data mapper step that is just before this connection, map the chart subtitle from a source field or property to the
subtitle
target field.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
-
If you want to add any other connections to the flow, add them now. Then return to these instructions.
-
In the integration visualization, click the plus sign that is just before the connection that adds a chart.
-
Click Data Mapper.
In the data mapper, map source properties, source fields, or source constants to the target Google Sheets connection, which is adding a chart. The following instructions assume that there is a source field, a source property, or a source constant that contains the value that you want to map to each target field.
If there is no source for the required value, then create a source property in the data mapper by clicking the + sign that is to the right of the Properties folder. In the Create Property dialog, give the property a name that makes it easy to map to the correct target field, for example, specify
overlayPosition
as the property name. For the property value, specify the value that you want the connection to use to create the chart. The chart’s overlay position field requires A1 notation that identifies a cell. That is, it specifies a start position but an end position specification is not required, and it is ignored if it is present. For example, specify something likeD4
as the value of the overlayPosition source property. Save the new property.When you configured the Add charts action, you might have specified a value for the spreadsheet ID, the chart title, and/or the chart subtitle. If you did, then do not map a value to that field.
-
To add a chart to a sheet, map source properties, source fields or source constants to target fields as follows:
-
Set the location of the chart by mapping an A1 notation value, which identifies a cell, to the overlayPosition target field. An end position is not required and it is ignored if present. The mapped value identifies the cell where Google Sheets places the chart. This cell is the upper left corner of the chart display.
If you do not map a value to the overlayPosition field, and you also do not map a value to the sheetId field, which identifies the sheet that you want to add the chart to, then the default behavior is that Google Sheets creates a new sheet and places the chart in A1.
You must map a value to the overlayPosition field if you plan to map a value to the sheetId field.
-
Map a source spreadsheetId field to the target spreadsheetId field. The connection uses source data in this spreadsheet to add the chart to a sheet in this same spreadsheet. The source data and the chart can be in two different sheets in the same spreadsheet but they cannot be in two different spreadsheets.
-
Set a chart title by mapping to the target title field. The connection inserts this string as the title of the chart.
-
Set a chart subtitle by mapping to the target subtitle field. The connection inserts this string as a chart subtitle.
-
Identify the sheet to add the chart to by mapping an integer to the sheetId field.
If you map a value to the sheetId field then you must also map a value to the overlayPosition field.
If you do not map a value to the sheetId field and you also do not map a value to the overlayPosition field, then the connection creates a new sheet and adds the chart to the new sheet.
If you do not map a value to the sheetId field but you do map a value to the overlayPosition field, then the connection places the chart on the sheet identified by the sourceSheetId field. This is the sheet that provides the data for the chart.
0
identifies the first sheet in the spreadsheet. For subsequent sheets, the sheet ID is at the end of the URL when the sheet is visible in a browser. For example, at the end of the following URL, you can seegid=206589330
:https://docs.google.com/spreadsheets/d/1pa…ngQbKkM/edit#gid=206589330
This indicates that the sheet ID is
206589330
and that is the value that you would map to sheetId. -
Identify the sheet that provides the data for the chart by mapping its integer sheet ID to the target sourceSheetId field. The default is
0
, which identifies the first sheet in the spreadsheet.You can add a basic chart or a pie chart. Follow one of the following sets of instructions according to the kind of chart that you want to add.
-
To add basic chart, in the target panel, expand the basicChart folder and map source fields to target fields that are in the basicChart folder:
-
Set the chart type (
BAR
,LINE
,AREA
, orCOLUMN
) by mapping to the target type field. The default isCOLUMN
. -
Set the title for the bottom axis of the chart by mapping to the target axisTitleBottom field.
-
Set the title for the left axis of the chart by mapping to the target axisTitleLeft field.
-
Set the high level category of information that the chart shows by mapping to the target domainRange field. This field uses the Google Sheets A1 notation. For example, suppose that the first column in a source sheet provides a list of 5 products in
A2
throughA6
, and you want the chart to provide some data for each product. In this column, the first cell (A1
) must contain a label, such asProducts
. The setting of domainRange would beA1:A6
. The chart will contain the data that is inA2
throughA6
. The chart does not display the label. -
Identify the location of the source data that the chart shows by mapping to the target dataRange field. This field uses the Google Sheets A1 notation. A chart can provide only one series of data. Continuing with the domainRange example, suppose that the second column in a source sheet shows the number sold for each of the 5 products that are listed in the first column and this is the data that you want the chart to show. In this column, the first cell (
B1
) must contain a label, such asNumber Sold
. The setting of dataRange would beB1:B6
. The chart will contain the data that is inB2
throughB6
. The chart does not display the label.
-
-
To add a pie chart, in the target panel, expand the pieChart folder and map source fields to target fields that are in the pieChart folder:
-
Set the location of the pie chart legend by mapping to the target legendPosition field. The default is
LEFT_LEGEND
. The value must beBOTTOM_LEGEND
,LEFT_LEGEND
,RIGHT_LEGEND
,TOP_LEGEND
, orNO_LEGEND
. -
Set the high level category of information that the pie chart shows by mapping to the target domainRange field. This field uses the Google Sheets A1 notation. For example, suppose that the first column in a source sheet provides a list of 5 products in
A2
throughA6
, and you want the chart to provide some data for each product. In this column, the first cell (A1
) must contain a label, such asProducts
. The setting of domainRange would beA1:A6
. The chart will contain the data that is inA2
throughA6
. The chart does not display the label. -
Identify the location of the source data that the chart shows by mapping to the target dataRange field. This field uses the Google Sheets A1 notation. A chart can provide only one series of data. Continuing with the domainRange example, suppose that the second column in a source sheet shows the number sold for each of the 5 products that are listed in the first column and this is the data that you want the chart to show. In this column, the first cell (
B1
) must contain a label, such asNumber Sold
. The setting of dataRange would be B1:B6. The chart will contain the data that is inB2
throughB6
. The chart does not display the label.
-
-
In the upper right, click Done to add the data mapper step.
-
Adding a pivot table to a sheet
In the middle of a flow, or to finish a simple integration, you can add a pivot table to a Google Sheets spreadsheet. A pivot table lets you aggregate, sort, or apply a function to spreadsheet data and display the results in the same spreadsheet. To add a pivot table, add a Google Sheets connection to the middle of a flow or as a simple integration’s finish connection. Then add a data mapping step before the connection. In the data mapping step, you set options that determine the location, properties, and content of the pivot table.
In this release, the Add pivot table action is limited to defining one value group, one row pivot group, and one column pivot group. Support for multiple groups in a single action is expected to be added in a future release. As a workaround, you can add multiple Google Sheets connections that add pivot tables based on the same source spreadsheet.
-
You created a Google Sheets connection that is authorized to access the Google spreadsheet that you want to add a pivot table to.
-
You have access to the ID for the spreadsheet that contains the source data for the pivot table.
-
You are creating or editing a flow and Syndesis is prompting you to add to the integration. Or, Syndesis is prompting you 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 a Google Sheets connection that is authorized to access the spreadsheet that you want to add the pivot table to.
-
On the Choose an action page, select Add pivot tables.
-
To configure the Add pivot tables action, in the SpreadsheetId field, do one of the following:
-
Enter the ID of the spreadsheet that you want to add a pivot table to.
-
Leave the field blank. In the data mapper step that you will add just before this connection, you will map the spreadsheet ID from a previous connection to this connection. The previous connection must access the spreadsheet that you want to add a pivot table to in this connection.
-
-
Click Next to add the connection to the flow. The connection appears in the integration visualization where you added it.
-
If you want to add any other connections to this flow, add them now. Then return to these instructions.
-
In the integration visualization, click the plus sign that is just before the connection that adds a pivot table to a sheet.
-
Click Data Mapper.
In the data mapper, map source properties, source fields, or source constants to the target Google Sheets connection, which is adding a pivot table. The following instructions assume that there is a source field, source property, or source constant that contains the value that you want to map to each target field.
If there is no source for the required value, then create a source property in the data mapper by clicking the + sign that is to the right of the Properties folder. In the Create Property dialog, give the property a name that makes it easy to map to the correct target field, for example, specify
valueLayout
as the property name. Specify the value that you want the connection to use to create the pivot table. The pivot table’s value layout field requires a value ofHORIZONTAL
orVERTICAL
so you might specifyVERTICAL
as the value of the valueLayout property. Save the new property. -
In the data mapper, configure a new pivot table as follows:
-
Map a source spreadsheetId field to the target spreadsheetId field. The connection uses source data in this spreadsheet to add the pivot table to a sheet in this same spreadsheet. The source data and the pivot table can be in two different sheets in the same spreadsheet but they cannot be in two different spreadsheets.
-
Identify the sheet to add the pivot table to by mapping an integer to the sheetId field. The default is
0
, which identifies the first sheet in the spreadsheet. For subsequent sheets, the sheet ID is at the end of the URL when the sheet is visible in a browser. For example, at the end of the following URL, you cangid=206589330
:https://docs.google.com/spreadsheets/d/1pa…ngQbKkM/edit#gid=206589330
.This indicates that the sheet ID is
206589330
and that is the value that you would map to sheetId. -
Identify the sheet that provides the data for generating the pivot table by mapping its integer sheet ID to the target sourceSheetId field. If you do not map a value to sourceSheetId, the connection uses the sheetId value, or
0
if no value is mapped to sheetId.0
identifies the first sheet in the spreadsheet. -
Set the source data range for generating the pivot table by mapping an A1 notation value to the target sourceRange field. For example, A2:D5.
-
Set the value layout to be used on the pivot table by mapping to the target valueLayout field. The value must be
VERTICAL
orHORIZONTAL
, which is the default.HORIZONTAL
specifies that values are laid out as columns. -
Set the top left cell of the pivot table by mapping an A1 notation cell coordinate to the target start field. When the connection adds the pivot table to the sheet that contains the source data, if you do not map a value to the start field, the default is that the top left cell of the pivot table is the cell that is in the first row of the source data range and in the first empty column after the source data range. When the source data is in one sheet and the pivot table will be in another sheet, the default is A1.
-
To add a value group, expand valueGroups in the target panel, and map values to the fields under valueGroups:
-
Map a value group name to the target name field.
-
Map a function, which you want to apply to the value group, to the target function field. The value must be
SUM
,COUNT
,AVERAGE
,MAX
,MIN
, orCUSTOM
. The default isSUM
. MapCUSTOM
to function when you are defining a formula. -
Map a custom formula, which you want to apply to the value group, to the target formula field if you mapped the
CUSTOM
value to the function field. -
Map a column name, which is the coordinate that builds the value group, to the target sourceColumn field.
-
-
To add a row pivot group, expand columnGroups in the target panel, and map values to the fields under columnGroups:
-
Map a row pivot group name to the target label field.
-
Map the sort order that you want to apply to the row pivot group to the target sortOrder field. The value must be
ASCENDING
orDESCENDING
. The default isASCENDING
. -
Map
true
orfalse
to the target showTotals field. The default istrue
, which enables the display of totals for the row pivot group. -
Map a column name, which is the coordinate that builds the row pivot group, to the target sourceColumn field.
-
-
To add a column pivot group, expand rowGroups in the target panel, and map values to the fields under rowGroups:
-
Map a column pivot group name to the target label field.
-
Map the sort order that you want to apply to the column pivot group to the target sortOrder field. The value must be
ASCENDING
orDESCENDING
. The default isASCENDING
. -
Map
true
orfalse
to the target showTotals field. The default istrue
, which enables the display of totals for the column pivot group. -
Map a column name, which is the coordinate that builds the column pivot group, to the target sourceColumn field.
-
-
In the upper right, click Done to add the data mapper step.
-
Connecting to HTTP and HTTPS endpoints
In an integration, you can connect to HTTP and HTTPS endpoints to execute
the GET
, PUT
, POST
, DELETE
, HEAD
, OPTIONS
, TRACE
,
or PATCH
method. To do this, create
an HTTP or HTTPS connection and then add it to an integration flow.
The following topics provide details:
Creating a connection to an HTTP or HTTPS endpoint
In an integration, to execute the HTTP GET
, PUT
, POST
, DELETE
,
HEAD
, OPTIONS
, TRACE
, or PATCH
method, create a connection to
an HTTP or HTTPS endpoint. You can then add the connection to one
or more integrations.
You must know the URL for the endpoint that 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.
-
If you want to use Hyper Text Transfer Protocol to connect to the endpoint, then click the HTTP connector. If you want to use Hyper Text Transfer Protocol Secure, then click the HTTPS connector.
-
In the Base URL field, enter the endpoint path. For example,
www.mycompany.com/sales
. -
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise specification of the base URL 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, enter
HTTPS My Company Sales
. -
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 HTTPS My Company Sales appears as a connection that you can choose to add to an integration.
Adding an HTTP or HTTPS connection to an integration
You can add an HTTP or HTTPS connection to any number of integrations.
-
You created an HTTP or HTTPS 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 start connection, or 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 HTTP or HTTPS connection that you want to add to the flow.
-
Select the action that you want the connection to perform:
-
If you are adding a start connection, then Periodic invoke URL is the only available action. This action invokes the endpoint at intervals that you specify and triggers the integration if the endpoint returns any data.
-
If you are adding a middle or finish connection, then Invoke URL is the only available action. This action invokes the endpoint once.
-
-
In the URL Path field, specify the location of the endpoint that you want to invoke.
-
In the HTTP Method field, select the method that you want the connection to perform. The default method is
GET
.-
GET
obtains the content at the URL path. -
PUT
replaces the content at the URL path with the integration data. -
POST
stores the integration data at the URL path to create new content. -
DELETE
removes content at the URL path. -
HEAD
obtains metadata about the content at the URL path. -
OPTIONS
obtains communication option settings at the URL path. -
TRACE
obtains information for testing and diagnostic purposes. -
PATCH
partially updates the content at the URL path according to the integration data.
-
-
If you are adding a start connection, which periodically invokes the URL, then in the Period field, accept the default interval of 1 second or specify a number and its unit (milliseconds, seconds, minutes, or hours) to indicate how long to wait between invocations.
-
Click Next to specify the action’s input or 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 dislay 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 IRC
Internet Relay Chat (IRC) is a protocol that lets anyone with an IRC client send and receive text messages in real time. In an integration, a connection to IRC can do one of the following:
-
Trigger execution of a simple integration when an IRC nickname that you specify receives a private message. The integration passes the message to the next step in the flow. For example, you can designate an IRC nickname for receiving names of possible customers. Upon receiving a message, the integration could connect to Salesforce to create a lead.
-
Deliver a message to a particular channel. The message is from the nickname that you specify. For example, this is useful when an integration downloads a file from an FTP server and processes it in some way. An integration flow can send a message to a particular channel to indicate that the process was successful.
To connect to IRC in an integration, create an IRC connection and then add the connection to an integration flow. Details are in the following topics:
Creating an IRC connection
In an integration, an IRC connection can retrieve messages that are sent to an IRC nickname that you specify or send messages to a nickname on a channel. You can use the same IRC connection in any number of integrations.
-
You know the hostname and port of the IRC server that you want to connect to.
-
If the IRC server requires a password, you know the password.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display Syndesis connectors.
-
Click the IRC connector.
-
In the Hostname field, enter an IRC hostname. You can specify an IP address or a name, for example,
chat.freenode.net
. -
In the Port field, enter the port that the IRC server is listening on, for example,
6665
. -
In the Password field, if the IRC server requires a password, enter it here.
-
Click Validate. Syndesis immediately tries to validate the connection and displays a message that indicates whether validation is successful. If validation fails, revise the connection configuration values 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, enter
IRC Freenode
. -
In the Description field, optionally enter any information that is helpful to know about this connection.
-
Click Save to see the updated list of available connections, including the connection that you just created. If you entered the example name, you would see that IRC Freenode appears as a connection that you can choose to add to an integration. You can add this connection to any number of integrations.
Adding an IRC connection to trigger integration execution upon receiving messages
An IRC connection that starts an integration triggers execution of the integration when the connection finds private messages that are sent to an IRC nickname that you specify.
-
You created an IRC connection.
-
You have an IRC nickname for receiving and sending messages.
-
You are creating a simple integration and Syndesis is prompting you to choose how you want to start the integration.
-
Click the IRC connection that you want to use to start the integration.
-
Select the IRC Receive Private Message action.
-
In the Channels field, optionally specify one or more IRC channels separated with commas.
-
In the Nickname field, specify the IRC nickname that the integration uses. For any channels that you specify, this nickname joins the channel. During execution, the integration retrieves messages that are sent to this nickname and passes them to the next step in the integration.
-
In the NickServ Password field, if the specified nickname has a password, enter it.
-
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 to add the connection to the flow.
The connection is a simple integration’s start connection and Syndesis prompts you to choose the integration’s finish connection.
Adding an IRC connection to send a message
In an integration, you can send a message to one or more IRC channels in the middle of a flow or to finish a simple integration. To do this, add an IRC connection to the middle of a flow or as a simple integration’s finish connection.
-
You created an IRC connection.
-
You have an IRC nickname for receiving and sending messages.
-
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 IRC connection that you want to add to the flow.
-
Select IRC Send Message to Channel to send a message to one or more channels.
-
In the Channels field, enter one or more IRC channels delimited by commas. During execution, this connection sends messages from the IRC nickname that you specify to these channels.
-
-
In the Nickname field, specify the IRC nickname that sends messages to the specified channels.
-
In the NickServ password field, if the nickname that you specified has a password, specify it here.
-
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 to add the connection to the flow.
The connection appears in the flow visualization where you added it.
Connecting to Jira
In an integration, you can connect to a Jira server to obtain, create, or update issues. Jira is a tool for planning, tracking, and managing software development projects. Each Jira environment allows customization of the workflow, which has an effect on the details for connecting to Jira in an integration. Consulting with your Jira administrator should clarify the details.
The following topics provide information and procedures for creating integrations that connect to a Jira server:
Registering Syndesis with a Jira server that uses OAuth
An integration can connect to a Jira server that uses the OAuth protocol to authenticate access. To enable this, register your Syndesis environment as a Jira client application. Jira client applications are also referred to as Jira consumers. In other words, your Syndesis environment is a Jira consumer.
| Registration is not required when a Jira server uses only basic authentication. |
Follow the procedure here to obtain the Jira OAuth credentials that you need to create a Syndesis connection to Jira. For more details about registering Jira consumers, including a tutorial that takes you through the steps with a sample server, see the Jira documentation about OAuth for REST APIs
After you register Syndesis with a Jira server, you use Syndesis to create a connection to that Jira server. Any number of integrations can use the same Jira connection. However, if you want to create another Jira connection, you must obtain another set of OAuth credentials by repeating the registration procedure provided here.
The main steps in the registration procedure are:
-
Obtain the Atlassian command line application that enables you to obtain OAuth credentials.
-
Run the downloaded application to create a
config.properties
file. -
Create a public/private key pair, which Syndesis uses to access a Jira server.
-
Edit the
config.properties
file to update some of its values. -
Configure your Jira server to recognize your Syndesis environment as a consumer application.
-
Obtain a Jira access token that Syndesis needs to access data on your Jira server.
Each of these steps has several substeps and the procedure below provides the details.
-
Jira server administration permissions.
-
Familiarity with command line interfaces.
-
Obtain the Atlassian command line application that enables you to obtain OAuth credentials:
-
In the left panel, at the bottom, click Downloads.
-
On the Downloads page, click Download repository.
-
Extract the file into a directory that you choose.
-
Run the downloaded application to create a
config.properties
file for OAuth credentials:-
In a terminal, navigate to the directory that contains the extracted content.
-
Change to the
java
directory and build the client:cd atlassianlabs-atlassian-oauth-examples-dd0264cad043/java mvn clean compile assembly:single
-
Change to the
target
directory and generate theconfig.properties
file:cd target java -jar OAuthTutorialClient-1.0.jar requestToken
You can ignore the connection exception. In the
target
directory, there is now aconfig.properties
file that contains some temporary keys. -
-
Generate a public/private key pair that Syndesis needs for access to a Jira server. While you can run these commands anywhere, the first instruction directs you to a particular directory for convenience:
-
Navigate to the directory that contains the downloaded application.
-
Generate a private key:
openssl genrsa -out jira_privatekey.pem 1024
-
Obtain a public key:
openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
This command prompts you to enter information about your Syndesis environment. Alternatively, to avoid responding to prompts, add the
-subj
option to the command. For example, at the end of the command line above, add something like this:-subj "/C=US/ST=New York/L=New York/O=MyCompany Ltd./OU=IT/CN=mysubdomain.mydomain.com"
-
Export the keys:
openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8 openssl x509 -pubkey -noout -in jira_publickey.cer > jira_publickey.pem
You now have four files:
jira_privatekey.pcks8
jira_privatekey.pem
jira_publickey.cer
jira_publickey.pem
-
Obtain the private key, without the header, line breaks, and footer:
cat jira_privatekey.pcks8 | grep -v 'PRIVATE'|awk '{print}' ORS=''
-
Copy the private key to the clipboard.
-
-
Edit the
config.properties
file:-
Navigate to the
java/target
directory that contains theconfig.properties
file and open the file for editing. -
In the
config.properties
file, replace the private key with the private key that you copied to the clipboard. -
Change the
jira_home
setting to the URL for your Jira server. Be sure to specifyhttps
if your Jira server useshttps
. Also, you need to escape the colon. For example:jira_home=https\://issues.mycompany.org
-
Change the
consumer_key
setting toSyndesis App
. For example:consumer_key=Syndesis App
-
Save and close the
config.properties
file.
-
-
Configure your Jira server to recognize your Syndesis environment as a consumer application. You must be logged in to the Jira server as an administrative user.
-
Select Settings () > Products > Application links.
-
In the Create new link input field, enter any URL, for example, enter:
https://example.com
.This displays a dialog that indicates that no response was received, which is okay because only one-way communication is required.
-
Click Continue to display the Link applications dialog. In this dialog:
-
In the Consumer Key field, enter
Syndesis App
. -
At the bottom, select Create incoming link.
-
In each of the other fields, enter any value. Each field requires a value. The value that you enter does not matter because no response is needed.
-
Click Continue to display another dialog.
-
In the Consumer Key field, enter
Syndesis App
. -
In the Consumer Name field, enter
Syndesis App
. -
In the Public Key field, paste the public key that is in the
jira_publickey.pem
file. Be sure to paste only the key without the header and footer. To display the key so that you can copy it, in the directory that contains thejira_publickey.pem
file, entercat jira_publickey.pem
. -
Click Continue.
-
-
-
Obtain a Jira access token that Syndesis needs to access data on your Jira server. In the Jira OAuth documentation that is linked to at the beginning of this procedure, this step is referred to as "The Oauth dance" because there are exchanges among Syndesis, the Jira server, and the Jira administrator.
-
Navigate to the
java/target
directory in the directory that contains the command line application that you downloaded in the first step of this whole procedure. -
Obtain a request token from your Jira server:
java -jar OAuthTutorialClient-1.0.jar requestToken
This displays something like:
Token: ec3dj4byySM5ek3XW7gl7f4oc99obAlo Token Secret: OhONj0eF7zhXAMKZLbD2Rd3x7Dmxjy0d Retrieved request token. go to https://jira101.atlassian.net/plugins/servlet/oauth/authorize?oauth_token=ec3dj4byySM5ek3XW7gl7f4oc99obAlo to authorize it
-
In another browser tab, go to the URL provided in that output. That page welcomes you to Jira and prompts you to allow access to the Syndesis App.
-
Click Allow, which displays an Access Approved page with a verification code.
-
Copy the verification code to the clipboard and paste it somewhere so that you can easily retrieve it.
-
Obtain an access token by invoking a command such as the following. In the following command line example, the last value is a verification code. In the command that you run, replace the example verification code with the verification code that you copied in the previous step. For example:
java -jar OAuthTutorialClient-1.0.jar accessToken qTJkPi
The output from this command is the access token that Syndesis needs to access your Jira server.
-
The Jira command line application updates the config.properties
file
so that it contains all values that you need to configure a
Jira connection for Syndesis.
Create a Jira connection.
Creating a Jira connection
In an integration, to obtain, create, or update a Jira issue, create a Jira connection, which you then add to an integration. You can add the same connection to any number of integrations.
If the Jira server that you want to connect to uses the OAuth protocol for authenticating access, you must have registered your Syndesis environment as a client of the Jira server that you want to connect to. See Registering Syndesis with a Jira server that uses OAuth.
-
For a Jira server that uses basic authentication, you have a Jira user name and password.
-
For a Jira server that uses OAuth, you have access to the
config.properties
file that contains values for the Jira access token, consumer key, private key, and verification code.
-
In Syndesis, in the navigation panel, click Connections to display any available connections.
-
Click Create Connection to display the available connectors.
-
Click the Jira connector.
-
In the Jira URL field, enter the URL for the Jira server that you want an integration to connect to, for example,
https://issues.mycompany.org
.For a connection to a Jira server uses OAuth, the procedure to register your Syndesis environment as a Jira consumer application resulted in a
config.properties
file. The URL that you specify here should be the same URL that is in thatconfig.preperties
file. For example, you would see a line like this in theconfig.properties
file:jira_home=https\:issues.mycompany.org
-
If this Jira server uses basic authentication:
-
In the User name field, enter a Jira user name. The connection uses this account to operate on the specified Jira server.
-
In the Password field, enter the specified user’s password.
Skip the next step if the Jira server does not use OAuth authentication.
-
-
If the Jira server uses OAuth authentication:
-
Open the
config.properties
file that contains the OAuth access token, keys, and verification code. This is the file that is the result of the registration procedure. Copy values from that file and paste them into the connection configuration fields. -
Copy the
access_token
value into the Access Token field. -
Copy the
consumer_key
value into the Consumer Key field. -
Copy the
private_key
value into the Private Key field. -
Copy the
secret
value into the Verification Code field.
-
-
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
Jira Connect 1
. -
In the Description field, optionally enter any information that is helpful to know about this connection. For example, enter
Sample Jira connection that uses the jkim account.
-
Click Save to see that the connection you created is now available. If you entered the example name, you would see that Jira Connect 1 appears as a connection that you can choose to add to an integration.
Obtaining Jira issues or comments to trigger integration execution
To trigger integration execution upon obtaining issues or comments from a Jira server, add a Jira connection as a simple integration’s start connection.
-
You created a Jira connection.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Jira connection that you want to use to start the integration.
-
On the Choose an action page, select an action:
-
Retrieve New Comments uses a query that you specify to search the Jira server. For each issue that the query returns, the connection checks whether a comment has been added since the previous invocation of the query. The connection returns any new comments.
-
Retrieve New Issues uses a query that you specify to search the Jira server. For each issue that the query returns, the connection checks its creation date. If the issue was created since the previous invocation of the query, the connection returns the issue to the integration. The first time that the connection executes this query, it returns all issues that it finds.
-
-
In the Delay field, accept the default of 5000 milliseconds (5 seconds) or enter the number of milliseconds that you want to elapse between query invocations.
-
In the Jira Query Language field, enter a Jira query. For example:
project = GATE AND assignee = jkim AND (status = Open OR status = New OR status = Reopened)
This query finds issues in the Gateway Online project, that are assigned to jkim and that are unresolved. Every Jira project has a short name and a long name. In this example, the short name of the Gateway Online project is GATE. In queries, specify a project’s short name.
The more specific the query is, the less time it takes to search the Jira server. When a query does not have any results, the connection does not trigger integration execution.
-
Click Next.
The connection starts a simple integration and Syndesis prompts you to choose the integration’s finish connection.
Adding an issue to a Jira server
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add an issue.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use to connect to a Jira server.
-
On the Choose an action page, select Add Issue.
-
Configure the action. The required fields are Issue type ID or name and Project key. For the optional fields, you can enter values now, or, after you add this connection to an integration, you can add a data mapper step before this connection. In the data mapper step, map fields from previous steps to the optional fields in this connection.
-
Optionally, in the Assignee field, enter the Jira user name for the person that you want to assign this issue to.
-
Optionally, in the Components field, enter the name of one or more components. Separate multiple names with commas. A Jira administrator defines the components that you can specify.
-
Optionally, in the Priority ID or name field, enter a priority for the new issue. A Jira administrator defines the priority values that you can enter.
-
Optionally, in the Summary field, enter a brief statement about the issue.
-
In the Issue type ID or name field, enter a value that describes the type of the issue. For example, this is often something like
Story
,Epic
,Chore
, orBug
.In Jira, a user with administrator permissions can see a list of valid issue types by selecting Project settings > Issue types. A user without these permissions can click in an issue’s type field and a list of allowable values should display.
-
Optionally, in the Watchers field, enter a comma-separated list of Jira user names. These people receive notifications when this issue is updated.
-
In the Project Key field, enter the short name of a Jira project that a Jira administrator has defined. The connection creates the new issue in this project. For example, a project key is something like
GATE
. -
Optionally, in the Description field, enter any information about this issue that it is helpful to capture.
-
-
Click Next.
The connection appears in the integration visualization where you added it.
Adding a comment to a Jira issue
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add a comment to an issue.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use to connect to a Jira server.
-
On the Choose an action page, select Add Comment.
-
In the Comment field, enter the comment that you want to add to the issue or plan to add a data mapper step before this connection. In that data mapper step, map the comment from a previous integration step to this connection’s comment field.
-
In the Issue Key field, enter the Jira identifier for the issue. Examples of issue keys:
GATE-1234
,Ent-239
. -
Click Next.
The connection appears in the integration visualization where you added it.
To map the comment from a previous integration step to this connection, add the connection that provides the comment content and then add a data mapper step before this Jira connection. For example, suppose a database connection obtains customer records. In the data mapper step, map the collection of customer records to the Jira connection’s comment field.
Attaching a file to a Jira issue
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to attach one or more files to an issue. In the integration, there must be a previous step that obtains the file(s) that you want to attach.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use to connect to the Jira server.
-
On the Choose an action page, select Attach File.
-
In the Issue Key field, enter the Jira identifier of the issue that you want to attach a file to. Examples of issue keys:
GATE-1234
,Ent-239
. -
Click Next.
The connection appears in the integration visualization where you added it.
If the integration does not already have an earlier connection that obtains the file(s) that you want to attach to a Jira issue, add that connection to the integration. Make sure that it is before the Jira connection that attaches a file. For example, suppose you add an FTP connection and download one or more files from an FTP server. When the integration executes, the subsequent Jira connection attaches those files to the Jira issue that you specified when you configured the attach file action.
Adding and removing Jira issue watchers
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to add watchers to an issue and/or remove watchers from issue.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use.
-
On the Choose an action page, select Add Issue.
-
In the Issue Key field, enter the Jira identifier of the issue that you want to add watchers to or remove watchers from. Examples of issue keys:
GATE-1234
,Ent-239
. -
Optionally, in the Add Watchers field, enter a comma-separated list of Jira user names. These people receive notifications when this issue is updated.
-
Optionally, in the Remove Watchers field, enter a comma-separated list of Jira user names that are already watching this issue. The connection removes these users from the list of watchers.
-
Click Next.
The connection appears in the integration visualization where you added it.
Updating an issue on a Jira server
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to update an issue. The connection can update one or more issue fields. If the issue being updated already has a value for a field, the connection replaces that value with any value you specify for the connection or that you map to a connection field. For example, if the issue already has a description, and you specify text in the Description field when you configure the Update Issue action, the connection replaces the description that was there with this new description.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use to connect to the Jira server.
-
On the Choose an action page, select Update Issue.
-
Configure the action. The only required field is Issue Key. For the optional fields, you can enter values now, or, after you add this connection to an integration, you can add a data mapper step before this connection. In the data mapper step, map fields from previous steps to the optional fields in this connection.
-
Optionally, in the Assignee field, enter the Jira user name for the person that you want to assign this issue to.
-
Optionally, in the Components field, enter the name of one or more components. Separate multiple names with commas. A Jira administrator defines the components that you can specify.
-
In the Issue Key field, enter the Jira identifier for the issue that you want the connection to update. Examples of issue keys:
GATE-1234
,Ent-239
. -
Optionally, in the Priority ID or name field, enter a priority for the new issue. A Jira administrator defines the priority values that you can enter.
-
Optionally, in the Summary field, enter a brief statement about the issue.
-
In the Issue type ID or name field, enter a value that describes the type of the issue. For example, this is often something like
Story
,Epic
,Chore
, orBug
. -
Optionally, in the Description field, enter any information about this issue that it is helpful to capture.
-
-
Click Next.
The connection appears in the integration visualization where you added it.
Transitioning a Jira issue to a new status
In the middle of a flow, or to finish a simple integration, you can connect to a Jira server to transition an issue to a new status, or to a new workflow stage. A Jira administrator defines what it means for an issue to transition as well as the values for transition IDs.
-
You created a Jira 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 simple integration’s finish connection.
-
On the Add to Integration page, click the plus sign where you want to add a Jira connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Jira connection that you want the integration to use to connect to the Jira server.
-
On the Choose an action page, select Transition Issue.
You do not need to specify any values to configure the transition issue action. Instead, you can map values from previous integration steps to the fields in the this connection.
-
Optionally, in the Comment field, enter a comment that you want to add to the issue.
-
Optionally, in the Issue Key field, enter the Jira identifier for the issue that is transitioning. Examples of issue keys:
GATE-1234
,Ent-239
. -
Optionally, in the ID of the transition field, enter an integer that a Jira administrator has associated with a particular transition, such as when a Jira moves from being new to being worked on, or when it moves from being worked on to being tested.
A Jira administrator can view transition IDs in a project’s workflow display. If you do not have administration permissions, obtain the allowed transition IDs from a Jira administrator.
-
Click Next.
The connection appears in the integration visualization where you added it.
If you did not specify a value in each Transition Issue field, ensure that the integration has a step that obtains the value for each field. After the integration has all required connections, add a data mapper step before the Jira connection that transitions an issue. In the data mapper step, map fields from previous steps to the fields in the Jira connection that transitions an issue.
Connecting to Kafka
Apache Kafka is a distributed streaming platform that you can use to obtain and publish data. In an integration, you can subscribe for data from a Kafka topic that you specify or publish data to a Kafka topic that you specify. To do this, enable Syndesis to discover the Kafka brokers in the cluster. Then create a connection to Kafka and add that connection to an integration flow. Details are in the following topics:
Enabling auto-discovery of Kafka brokers/AMQ Streams
In an integration, if you plan to connect to a Kafka broker that is an AMQ Streams instance, enable auto-discovery of such brokers before you create the Kafka connection. This makes creating the Kafka connection easier because Syndesis can provide Kafka broker details that are required to configure the connection.
To enable auto-discovery, you give an OpenShift user account privileges that allow that account to see resources on the cluster. The particular privileges that you assign let the account discover different subsets of brokers.
-
You installed the
oc
client tool and it is connected to the cluster in which you want to enable auto-discovery of Kafka brokers. -
You have cluster administration permissions.
-
Kafka broker(s) (AMQ Streams instances) that you want to connect to in an integration are installed in the same cluster as Syndesis.
-
Log in to OpenShift with an account that has cluster administration permissions. For example:
$ oc login -u admin -p admin
-
Ensure that the current project is the project in which Syndesis is running. To view the current project, invoke the following command:
$ oc project
-
Ensure that the Kafka brokers that you want an integration to connect to are installed in the cluster.
For example, to install Strimzi on minishift, follow the instructions at https://strimzi.io/quickstarts/okd/
-
Invoke the following command to apply the Strimzi installation file. In the command line, replace
myproject
with the name of the project in which Syndesis is running.oc apply -f https://github.com/strimzi/strimzi-kafka-operator/releases/download/0.15.0/strimzi-cluster-operator-0.15.0.yaml -n myproject
-
Invoke the following command to provision the Apache Kafka cluster. Replace
myproject
with the name of the project in which Syndesis is running.oc apply -f https://raw.githubusercontent.com/strimzi/strimzi-kafka-operator/0.15.0/examples/kafka/kafka-persistent-single.yaml -n myproject
-
Invoke the following command to deploy Kafka. Be sure to replace
mycluster
with the name of the cluster in which you are enabling auto-discovery, and replacemyproject
with the name of the project in which Syndesis is running.oc wait kafka/mycluster --for=condition=Ready --timeout=300s -n myproject
-
Create a producer for the Kafka broker that you specify. For example, in the following command:
-
myproject
is the name of the project in which Fuse Online is running. -
my-cluster-kafka-bootstrap:9092
identifies a Kafka broker. -
my-topic
is the name of the Kafka topic that a Kafka connection will be subscribed to.oc -n myproject run kafka-producer -ti --image=strimzi/kafka:0.15.0-kafka-2.3.1 --rm=true --restart=Never -- bin/kafka-console-producer.sh --broker-list my-cluster-kafka-bootstrap:9092 --topic my-topic
-
-
Give privileges that enable access to Kafka brokers in the cluster to an
oc
user account. How your cluster is configured determines the privileges that you need to grant. For example, for a Strimzi cluster on minishift, you can do the following:-
Create a cluster role that can access Kafka/Strimzi resources in the cluster. In the following example,
kafkas.kafka.strimzi.io-view
is the name of the new role:oc create clusterrole kafkas.kafka.strimzi.io-view --verb=get,list --resource=kafkas --resource=crd
-
Add this cluster role to an
oc
user. In the following example,syndesis-server
is the name of theoc
user account:oc adm policy add-cluster-role-to-user kafkas.kafka.strimzi.io-view -z syndesis-server
-
In Syndesis, when you create a Kafka connection, the connection configuration page displays the Kafka brokers that are available. You select the broker that you want the connection to access.
Creating a connection to a Kafka broker
In an integration, to subscribe for data from a Kafka topic or publish data to a Kafka topic, create a connection to Kafka and then add that connection to an integration.
-
You enabled auto-discovery of Kafka brokers in the cluster as described in Enabling auto-discovery of Kafka brokers/AMQ Streams. Or, you know the URI for the Kafka broker that you want to connect to.
-
If you want to use Transport Layer Security (TLS) to encrypt your data, you have the Kafka broker’s PEM certificate text. Typically, you obtain the broker certificate text from your Kafka server administrator.
-
In Syndesis, in the left panel, click Connections to display any available connections.
-
Click Create Connection to display connectors.
-
Click the Kafka Message Broker connector.
-
In the Kafka broker URIs field, select the broker that you want this connection to access, or enter a comma separated list of Kafka broker URIs. Each URI should be in the form host:port.
-
For the Transport Protocol field, select one of the following options:
-
If you want to encrypt your data to protect it in transit, select TLS (Transport Layer Security).
-
If you do not want to encrypt your data, select Plain and then skip to Step 7.
-
-
If you selected TLS in Step 5, then in the Broker certificate field, paste the Kafka broker’s PEM certificate text.
-
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 parameter 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
Kafka 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 Kafka West appears as a connection that you can choose to add to an integration.
Obtaining data from a Kafka broker to trigger integration execution
To trigger execution of an integration upon receiving data from a Kafka broker, add a Kafka connection as the start connection. When the integration is running, the Kafka connection continuously watches for data in the Kafka topic that you specify. When the connection finds new data, it passes that data to the next step in the integration.
You created a connection to a Kafka broker.
-
In the Syndesis panel on the left, click Integrations.
-
Click Create Integration.
-
On the Choose a connection page, click the Kafka connection that you want to use to start the integration.
-
On the Choose an action page, select the Subscribe action to receive data from the topic that you specify.
-
In the Topic Name field, click the down carat to display a list of topics and click the topic that you want to subscribe to. Or, type a topic name to create that topic.
-
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 Kafka connection output to a subsequent step then you must specify the data type. The data mapper does not recognize 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 prompts you to choose the finish connection.
Publishing data to a Kafka broker
In an integration, you can publish data to a Kafka broker in the middle of a flow or to finish a simple integration. To do this, add a Kafka connection to the middle of a flow or as a simple integration’s finish connection.
-
You created a connection to a Kafka broker.
-
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 a Kafka connection. Skip this step if you are adding a simple integration’s finish connection.
-
Click the Kafka connection that you want to use to publish messages.
-
On the Choose an action page, select Publish.
-
In the Topic Name field, click the down carat to display a list of topics and click the topic that you want to publish to.
-
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 integration visualization where you added it.
Connecting to Knative resources
You can create a simple integration that does any of the following:
-
Connects to a Knative channel to obtain or send messages
-
Exposes the integration as a Knative service
-
Calls a Knative service
The exchanged messages can be of any format, however, messages are typically in JSON format.