How to use IBM App Connect with IBM Cloudant

IBM Cloudant is a fully managed NoSQL Database as a Service (DBaaS) with powerful query, analytics, replication, and sync. Cloudant stores data as documents in JSON format.

Connecting to IBM Cloudant

To connect App Connect to an IBM Cloudant account that you want App Connect to use, you need the following connection details:

  • If your service instance uses IBM Cloud® Identity and Access Management (IAM) authentication only, or both legacy credentials and IAM, provide the following connection details:
    • Cloudant host is the hostname of the instance.
    • Cloudant API key is the API key for the instance.
  • If your service instance uses legacy credentials for authentication, provide the following connection details:
    • Cloudant username is the name of the service instance user.
    • Cloudant password is the password for the specified username.
    • The following example shows the fields that you must complete when you connect to IBM Cloudant by using IAM authentication only or both legacy credentials and IAM. Connect to Cloudant form
You can find the connection values on the Service credentials page for the service instance in IBM Cloud:
  1. Log in to IBM Cloud.
  2. From the IBM Cloud Dashboard, click the Cloudant service instance that you want to work with.
  3. To view the service credentials, click Service credentials, then click View credentials. (If you want to define new credentials to use, click New credential.)
    • If your service instance supports IAM authentication only, or both legacy credentials and IAM, copy the host and API key values, and paste them into the App Connect fields. Cloudant credentials (IAM)
    • If your service instance uses legacy (Cloud Foundry) authentication, copy the username and password, and paste them into the App Connect fields. Cloudant credentials

To connect to a IBM Cloudant endpoint from the App Connect Designer Connect > Applications and APIs page (previously the Catalog page) for the first time, expand IBM Cloudant, then click Connect. For more information, see Managing accounts.

Tip:

Before you use the account that is created in App Connect in a flow, rename the account to something meaningful that helps you to identify it. To rename the account on the Applications and APIs page, select the account, open its options menu (⋮), then click Rename Account.

What to consider first

Before you use App Connect Designer with IBM Cloudant, take note of the following considerations:

  • To use Cloudant with App Connect, you must provision a Cloudant NoSQL DB service on IBM Cloud.
  • To configure the New document action, the Document ID field is optional. If you do not specify a value or data mapping, IBM Cloudant assigns an ID to the document created.
  • You can specify your Cloudant document data structure as data properties (with name and data type) or as a JSON object that consists of comma-separated name-value pairs.
    • The following example shows a Cloudant document data structure that is specified as data properties. Cloudant document data structure as data properties

      To specify your Cloudant document data structure as data properties, click Add property under the 'Document data' heading. (If you have been specifying document data as JSON, make sure that the Document data field is empty, then click Add property.) For more information about specifying data properties, see Defining your own data properties.

    • The following example shows a Cloudant document data structure that is specified as JSON. Cloudant document data structure as JSON

      To specify your Cloudant document data structure as JSON, make sure that no properties are shown under the Document data heading, then click Edit mappings.

  • (General consideration) You can see lists of the trigger events and actions that are available on the Applications and APIs page of the App Connect Designer.

    For some applications, the events and actions depend on the environment and whether the connector supports configurable events and dynamic discovery of actions. If the application supports configurable events, you see a Show more configurable events link under the events list. If the application supports dynamic discovery of actions, you see a Show more link under the actions list.

  • (General consideration) If you are using multiple accounts for an application, the set of fields that is displayed when you select an action for that application can vary for different accounts. In the flow editor, some applications always provide a curated set of static fields for an action. Other applications use dynamic discovery to retrieve the set of fields that are configured on the instance that you are connected to. For example, if you have two accounts for two instances of an application, the first account might use settings that are ready for immediate use. However, the second account might be configured with extra custom fields.

Events and actions

IBM Cloudant events

These events are for changes in this application that trigger a flow to start completing the actions in the flow.

Note: Events are not available for changes in this application. You can trigger a flow in other ways, such as at a scheduled interval or at specific dates and times.

IBM Cloudant actions

Your flow completes these actions on this application.

Attachments
Create attachment
Retrieve attachments
Update or create attachment
Databases
Create database
Retrieve databases
Delete database
Documents
Create document
Retrieve documents
Update document
Update or create document
Delete document
Views
Apply view

More items are available after you connect App Connect to IBM Cloudant.

Examples

Dashboard tile for a template that uses IBM Cloudant

Use templates to quickly create flows for IBM Cloudant

Learn how to use App Connect templates to quickly create flows that complete actions on IBM Cloudant. For example, go to the Discover page and search for IBM Cloudant.

Learn more

Dashboard tile for a template that uses IBM Cloudant