App Connect Designer Authoring reference

Supported storage types for Apache CouchDB

The IBM App Connect Operator provides a CouchDB NOSQL database server to store flow definition artifacts within a volume in the container’s file system.

Before you create the App Connect Designer instance, you must decide what type of storage to use for CouchDB because you will need to specify this storage type while creating the instance and will not be able to change this setting after the instance is created.

The following storage types can be used to allocate storage for CouchDB:

Persistent storage

Persistent storage is recommended for extra resilience because the CouchDB database is retained when pods restart.

Note: When you delete a 12.0.8.0-r1 or earlier Designer instance, the CouchDB database is automatically deleted. However, when you delete a 12.0.8.0-r2 or later Designer instance, the CouchDB database is retained and needs to be manually deleted. From the Red Hat OpenShift web console, you can delete the CouchDB database by navigating to Storage > PersistentVolumeClaims and then deleting the PVC that is named in the format data-c-designerName-m-0. From the Red Hat OpenShift or Kubernetes CLI, you can delete the CouchDB database by running one of these commands:

oc delete pvc pvcName -n namespaceName

kubectl delete pvc pvcName -n namespaceName

A persistent volume must be dynamically provisioned through a storage class that is available on the cluster by using the spec.couchdb.storage.class parameter. Storage classes must support the following modes:

• Dynamic volume provisioning
• ReadWriteOnce (RWO) access modes
• volumeBindingMode: WaitForFirstConsumer (zone-local storage)
• POSIX filesystem compatibility (for example, not NFS)

The mode requirements map to the following preferred options for common public cloud environments:

Provider	Type	Storage class	Documentation
IBM Cloud	IBM Block Storage	ibm-block-*	Documentation
AWS	Elastic Block Storage	aws-ebs	Documentation
Azure	Azure Disk	default or managed-premium	Documentation

For Google Compute Engine (GCE), Persistent Disk can be used, but a storage class must be manually created to support dynamic provisioning.

For more information about persistent volumes, see Persistent Volumes in the Kubernetes documentation.

If you choose persistent storage, you will need to specify a storage class, storage size, and number of replica pods.

Ephemeral storage

With this storage type, an ephemeral volume is created to store the CouchDB database when a Designer pod is started. The ephemeral (emptyDir) volume exists only for the lifetime of the pod, so the CouchDB database will be lost when the pod restarts. You might typically choose this storage type if creating an environment for demonstration or testing.

To define the storage type for CouchDB when creating an App Connect Designer instance, you must specify your preferred type in the custom resource settings by setting the spec.couchdb.storage.type parameter and then complete the other spec.couchdb.storage.* parameters as appropriate for the selected storage type.

Supported storage types for the AI model

When you create an App Connect Designer instance, you can optionally choose to enable the incremental learning feature, which uses AI modeling techniques to improve the accuracy of source-to-target mapping suggestions that are offered in all authored flows. A supplied AI model is retrained at periodic intervals with training data that is collected about your mapping preferences.

Before you create the App Connect Designer instance, you must decide what type of storage to use for the AI model because you will need to specify this storage type and any associated settings while creating the instance.

The following storage types can be used to allocate storage for the AI model:

Persistent storage

With this storage type, the AI model is stored in a persistent volume in the container’s file system. The persistent volume can be dynamically provisioned through a storage class that is available on the cluster, or can be requested through a claim name. With persistent storage, the AI model is retained in the file system when pods restart and is deleted only when you delete the App Connect Designer instance.

Note: Persistent storage is applicable only if the spec.version value in the App Connect Designer custom resource resolves to 12.0.1.0-r1 or later.

Incremental learning requires a storage class with ReadWriteMany (RWX) capability. If using IBM Cloud, use the ibmc-file-gold-gid storage class.

If you choose persistent storage, you will need to specify a storage class or the name of an existing claim. (A storage size does not need to be manually specified because the allocated default is suitable for requirements.)

Simple Storage Service (S3) storage

S3 storage offers an alternative option to persistent storage, and supports the use of an object storage service for storing the AI model by using the S3 REST API.

Note: S3 storage is applicable only if the spec.version value in the App Connect Designer custom resource resolves to 12.0.1.0-r4 or later.

Restriction:

• S3 storage is not supported when the IBM App Connect Operator is installed in a restricted network because a cluster requires internet access to read and write training data from or to an S3 object store.
• Only Amazon S3 and IBM Cloud Object Storage S3 are supported as S3 providers.

The AI model will be stored as an object with read/write access in a specified bucket in your S3 instance and can be viewed in the S3 bucket. The AI model is stored in ZIP format in the following location in the bucket, and the ZIP object will be overwritten (with the same name) each time the model is retrained:

/mapping-assist-model/mapping_assist_v1.1.0.zip

Warning: Do not delete an AI model from the S3 bucket if that model is in use by a Designer instance because the accumulated data will be lost. Although a new base model will automatically be created for the Designer instance, this model will need to undergo training at the next scheduled interval (using data collated only during that interval) before being added to the S3 bucket.

If you choose S3 storage, you will need to specify the following storage settings for your provisioned S3 instance:

• The name of an existing bucket for storing the AI model

  You are not restricted from using an S3 bucket that already contains other objects because the AI model is separately stored in a dedicated folder (mapping-assist-model). If you want to enable S3 storage for AI models in multiple App Connect Designer instances, you must use a separate S3 bucket for each instance to ensure that the AI model for one instance does not get overwritten by the AI model for another instance.

• An S3 endpoint to which the S3 REST API sends requests for reading and writing objects

  You should be able to locate the available endpoints from your S3 instance. For example, on IBM Cloud Object Storage S3, you can locate the endpoints from the Endpoints page.

  To minimize latency, it is recommended that you use an S3 bucket that is in the same geographic area as your App Connect Designer instance. Also use an endpoint with a location or region that is similar to where Designer is deployed. For more information, see Endpoints and storage locations in the IBM Cloud Object Storage S3 documentation and Amazon Simple Storage Service endpoints and quotas in the Amazon Web Services documentation.

• S3 credentials for connecting to the bucket

  You will need to supply these credentials by creating a configuration of type S3Credentials. For more information, see Creating a configuration of type S3Credentials for use with App Connect Designer.

To define the storage type for the AI model when creating an App Connect Designer instance, you must specify your preferred type in the custom resource settings by setting the spec.designerMappingAssist.incrementalLearning.storage.type parameter and then complete the other spec.designerMappingAssist.incrementalLearning.storage.* parameters as appropriate for the selected storage type. If you want to create a Designer instance that uses S3 storage for the AI model, your must first create a configuration object of type S3Credentials to store the credentials for accessing the bucket.

Creating an instance from the IBM Cloud Pak Platform UI

To create an App Connect Designer instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the Platform UI.
   • Applicable to IBM App Connect Operator 11.0.0 or later: The Platform UI Instances page opens as the home page. The welcome banner includes a theme switcher that you can use to choose a light theme, a dark theme, or a custom theme that matches your existing system UI.
   • Applicable to IBM App Connect Operator 10.1.1 or earlier: The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

     
     From the navigation menu , expand Administration and click Integration instances.

2. From the Instances (or Integration instances) page, click Create an instance.
3. To create an App Connect Designer instance from the Create an instance page, click the Integration design tile and click Next.
4. From the Create an integration design instance page, click a tile to select which type of instance you want to create:
   • Quick start with AI enabled: Deploy an App Connect Designer instance with one replica pod, and with AI-powered mapping assist and transformation generation enabled.
     Consider choosing this option if you are the sole user or if you want to quickly get started for evaluative purposes, and additionally want to try out these features:

     • Mapping assist, which provides "smart mapping" that enables you to auto-populate the fields within a flow with the best possible matches from previous nodes
     • Transformation generation, which uses supplied sample data or drop-down list values to construct complex (JSONata) transformations that let you easily map source data to target data
   • Development with AI enabled: Deploy an App Connect Designer instance with multiple replica pods for resilience and high availability, and with AI-powered mapping assist and transformation generation enabled.
     Consider choosing this option to create a Development deployment that additionally provides the following features:

     • Mapping assist, which provides "smart mapping" that enables you to auto-populate the fields within a flow with the best possible matches from previous nodes
     • Transformation generation, which uses supplied sample data or drop-down list values to construct complex (JSONata) transformations that let you easily map source data to target data
   • Quick start: Deploy an App Connect Designer instance with one replica pod.

     Consider choosing this option if you are the sole user and want to quickly get started for evaluative purposes. AI-powered mapping assist and transformation generation are disabled by default.

   • Development: Deploy an App Connect Designer instance with multiple replica pods for resilience and high availability.

     Consider choosing this option for a multi-user environment with larger workloads than the Quick start deployment, with the capability to switch between replica pods to support failover. AI-powered mapping assist and transformation generation are disabled by default.

   • Select a template from Automation assets: (Applicable to IBM App Connect Operator 11.0.0 or later) Create a Designer instance by selecting an existing template from Automation assets. For more information, see Deploying an instance from a template in the IBM Cloud Pak for Integration documentation.
5. Click Next. A UI form view opens with the minimum configuration that is required to create the instance.
6. Complete either of the following steps:
   • To quickly get going, complete the standard set of configuration fields. You can display advanced settings in the UI form view by setting Advanced settings to on. Note that some fields might not be represented in the form.
     Note: Identity and access management (IAM) by using Keycloak is enabled by default although the authentication and authorization fields (which are used to enable or disable IAM) are not displayed in UI form view. For more information about using IAM with the instance that you are creating, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
     • Name: Enter a short distinctive name that uniquely identifies this Designer instance.
     • Namespace: Enter the name of the namespace (project) where you want to create the Designer instance. If the Platform UI is deployed in a single namespace (namespace-scoped), this namespace is displayed and cannot be changed.
     • Labels: (Applicable to IBM App Connect Operator 11.0.0 or later) Add one or more labels as key/value pairs, which can be used to organize and categorize (scope and select) instances. For more information, see Labels and Selectors.

       By default, a label is provided with a key of backup.appconnect.ibm.com/component and a value of designerauthoring. This label is used if you need to run backup and restore operations by using OpenShift API for Data Protection (OADP) and is ignored otherwise.

     • Channel or version: Select an App Connect product (fix pack) version that the Designer instance is based on. You can select a channel that will resolve to the latest fully qualified version on that channel, or select a specific fully qualified version. If you are using IBM App Connect Operator 7.1.0 or later, the supported channels or versions will depend on the Red Hat OpenShift version that is installed in your cluster. For more information about these values, see spec.version values.
     • Accept: Review the license in the supplied link and then click this check box to accept the terms and conditions.
     • License LI: Select a license identifier that aligns with the channel or the fully qualified version that you selected. For more information, see Licensing reference for IBM App Connect Operator.
     • License use: Select an appropriate CloudPakForIntegration or AppConnectEnterprise license type that you are entitled to use.
       IAM entitlements:

       • If you purchased Cloud Pak for Integration, you are entitled to use either CloudPakForIntegration* or AppConnectEnterprise* style licenses. However, to use a CloudPakForIntegration* license, a Platform UI instance must be deployed.
       • If you purchased the IBM App Connect Operator for an independent deployment, you are restricted to AppConnectEnterprise* style licenses regardless of whether IAM is enabled or disabled. (Although installation of the Cloud Pak for Integration and other Operators is permitted for configuring IAM, you are not allowed to deploy the Platform UI.)
     • Replicas: Specify the number of replica pods to run for this deployment.
     • Enable Mapping Assist: Set this switch to on to enable the Mapping Assist components.

       Consider whether you want to enable Mapping Assist for smart mapping and data transformation (which requires extra resources). You can also optionally enable Mapping Assist incremental learning to use AI modeling for enhanced smart mapping. If you enable incremental learning, you'll need to specify a "learning" frequency, and indicate whether the AI model should be stored in a persistent volume or an S3 bucket. If you are using an S3 bucket, you'll need to provide details for connecting to this bucket, including the name of the configuration object of type S3Credentials, which you created to store your S3 credentials. In YAML view, you can use the spec.designerMappingAssist.enabled and spec.designerMappingAssist.incrementalLearning.* parameters to configure the Mapping Assist features. For more information about Mapping Assist and the configuration object for S3 storage, see Simplifying data mapping and data transformation with AI-powered suggestions and Creating a configuration of type S3Credentials for use with App Connect Designer.

     • Storage type: Select the type of storage to use for CouchDB.
       • persistent-claim: Choose this option for storage in a persistent volume in the container’s file system. Retains the existing configuration, logs, and persistent messages when pods restart.
       • ephemeral: Choose this option for storage in an ephemeral volume that exists only for the lifetime of the pod.
     • Storage class: Select a supported storage class for your cluster, which should be used to dynamically provision a persistent volume that belongs to that class. This value is required if Storage type is set to persistent-claim.
       IAM requirement: Keycloak requires block storage and a storage class that is set as the default class. For more information, see Storage options for Keycloak in the IBM Cloud Pak for Integration documentation.
     • Size: Specify the maximum amount of storage required for a persistent volume for CouchDB in decimal or binary format; that is, Gi or G. This value is required if Storage type is set to persistent-claim.

     Set Advanced settings to on if you want to specify any advanced settings from the UI form view.

     • Advanced: Log Level: Select the level of information to display in the CouchDB logs. Valid values are info, warning, error, debug, and notice.
     • Advanced: Replicas: Specify the number of CouchDB replica pods to run between 1-10.
     • Advanced: Secret to use for pulling images: Specify an optional list of references to secrets in the same namespace to use for pulling any of the images used. If specified, these secrets are passed to individual puller implementations for them to use. For example, in the case of Docker, only DockerConfig type secrets are honored. For more information, see https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod.
     • Runtime Container Image name & tag: Specify the path to the Docker image for the runtime container.
     • Runtime Container ImagePullPolicy: Indicate whether you want images for the runtime container to be pulled every time, never, or only if they are not present. Valid values are Always, Never, and IfNotPresent.
     • Runtime Container (Resource requirements): Specify resource requirements for running the runtime container. For information about the values that you can specify, see the spec.integrationServer.containers.runtime.resources.* parameters in Custom resource values.
   • For a more advanced configuration, click YAML to switch to the YAML view and then update the editor with your required parameters.
     • For information about the available parameters and their values, see Custom resource values.
       
       In the default parameters that are presented, be aware that a value is required for spec.couchdb.storage.class (and for spec.couchdb.storage.size) when spec.couchdb.storage.type is set to persistent-claim. The spec.couchdb.storage.class value must match a supported storage class for your cluster. (The UI form view presents these classes in a drop-down list.)

       spec:
         couchdb:
           storage:
             class: 'storageClassValue'
             size: 10Gi
             type: persistent-claim

7. Click Create. You are redirected to the Instances (or Integration instances) page. An entry for the instance is shown in the table with an initial status of Pending, which you can click to check the progress of the deployment. When the deployment completes, the status changes to Ready.
   

What to do next

1. If IAM with Keycloak is enabled for this instance, use the Keycloak Admin Console to manage user access to the instance by setting up users with assigned roles. For more information, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
2. Share the URL of the Platform UI with the configured users and supply the authentication credentials that they can use to log in to the Platform UI and Designer instance.

   The authorized users can access the Designer (Integration design) instance by clicking the name in the Platform UI, and then use the instance to author flows.

Creating an instance from the Red Hat OpenShift web console

To create an App Connect Designer instance by using the Red Hat OpenShift web console, complete the following steps:

1. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
2. From the navigation, click Operators > Installed Operators.
3. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
4. From the Installed Operators page, click IBM App Connect.
5. From the Operator details page for the App Connect Operator, click the Designer Authoring tab. Any previously created Designer instances are displayed in a table.
6. Click Create DesignerAuthoring.

   From the Details tab on the Operator details page, you can also locate the Designer Authoring tile and click Create instance to specify installation settings for the instance.

7. To use the Form view, ensure that Form view is selected and then complete the fields. Note that some fields might not be represented in the form.
   • Name: Enter a short distinctive name that uniquely identifies this Designer instance.
   • Labels: (Applicable to IBM App Connect Operator 11.0.0 or later)

     By default, a label is provided with a key of backup.appconnect.ibm.com/component and a value of designerauthoring. This label is used if you need to run backup and restore operations by using OpenShift API for Data Protection (OADP) and is ignored otherwise. For more information, see Backing up and restoring your IBM App Connect resources and persistent volumes on Red Hat OpenShift.

   • License/Accept: Select this checkbox to accept the terms and conditions of the license.
   • License/License LI: Select a license identifier that aligns with the channel or the fully qualified version that you selected. For more information, see Licensing reference for IBM App Connect Operator.
   • License/License use: Select an appropriate CloudPakForIntegration or AppConnectEnterprise license type that you are entitled to use.
     IAM entitlements:

     • If you purchased Cloud Pak for Integration, you are entitled to use either CloudPakForIntegration* or AppConnectEnterprise* style licenses. However, to use a CloudPakForIntegration* license, a Platform UI instance must be deployed.
     • If you purchased the IBM App Connect Operator for an independent deployment, you are restricted to AppConnectEnterprise* style licenses regardless of whether IAM is enabled or disabled. (Although installation of the Cloud Pak for Integration and other Operators is permitted for configuring IAM, you are not allowed to deploy the Platform UI.)
   • Couch DB/storage/Storage type: Select the type of storage to use for CouchDB.
     • persistent-claim: Choose this option for storage in a persistent volume in the container’s file system. Retains the existing configuration, logs, and persistent messages when pods restart.
     • ephemeral: Choose this option for storage in an ephemeral volume that exists only for the lifetime of the pod.
   • Couch DB/storage/Storage class: Select a supported storage class for your cluster, which should be used to dynamically provision a persistent volume that belongs to that class. This value is required if Storage type is set to persistent-claim.
     IAM requirement: Keycloak requires block storage and a storage class that is set as the default class. For more information, see Storage options for Keycloak in the IBM Cloud Pak for Integration documentation.
   • Couch DB/storage/Log Level: Select the level of information to display in the CouchDB logs. Valid values are info, warning, error, debug, and notice.
   • Couch DB/storage/Replicas: Specify the number of CouchDB replica pods to run between 1-10.
   • Channel or version: Select an App Connect product (fix pack) version that the Designer instance is based on. You can select a channel that will resolve to the latest fully qualified version on that channel, or select a specific fully qualified version. If you are using IBM App Connect Operator 7.1.0 or later, the supported channels or versions will depend on the Red Hat OpenShift version that is installed in your cluster. For more information about these values, see spec.version values.
   • Replicas: Specify the number of replica pods to run for this deployment.
   • Designer Mapping Assist/Enable Mapping Assist: Set this switch to true to enable the Mapping Assist components.

     Consider whether you want to enable Mapping Assist for smart mapping and data transformation (which requires extra resources). You can also optionally enable Mapping Assist incremental learning to use AI modeling for enhanced smart mapping. If you enable incremental learning, you'll need to specify a "learning" frequency, and indicate whether the AI model should be stored in a persistent volume or an S3 bucket. If you are using an S3 bucket, you'll need to provide details for connecting to this bucket, including the name of the configuration object of type S3Credentials, which you created to store your S3 credentials. In YAML view, you can use the spec.designerMappingAssist.enabled and spec.designerMappingAssist.incrementalLearning.* parameters to configure the Mapping Assist features. For more information about Mapping Assist and the configuration object for S3 storage, see Simplifying data mapping and data transformation with AI-powered suggestions and Creating a configuration of type S3Credentials for use with App Connect Designer.

   Expand the Advanced configuration section if you want to specify any advanced settings in Form view.

   • Authentication and Authorization:
     • Authentication/integrationKeycloak/Enabled: Select this checkbox to control access to the Designer instance by using identity and access management (IAM) to validate user identities.
     • Authorization/integrationKeycloak/Enabled Select this checkbox to control access to the Designer instance by using IAM to grant access permissions.

     You must select both of these checkboxes to enable Keycloak, which implements IAM. Keycloak is enabled by default. For more information about using IAM with the instance that you are creating, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.

     If you do not want to restrict access to the instance, you must clear both of the Enabled checkboxes. Also ensure that you are using an AppConnectEnterprise* style license.

     Restriction: These settings are not applicable for Kubernetes environments.
   • Secret to use for pulling images: Specify an optional list of references to secrets in the same namespace to use for pulling any of the images used. If specified, these secrets are passed to individual puller implementations for them to use. For example, in the case of Docker, only DockerConfig type secrets are honored. For more information, see https://kubernetes.io/docs/concepts/containers/images/#specifying-imagepullsecrets-on-a-pod.
   • Integration Server Pod/containers:
     • Integration Server Pod/containers/runtime/Image name & tag: Specify the path to the Docker image for the runtime container.
     • Integration Server Pod/containers/runtime/ImagePullPolicy: Indicate whether you want images for the runtime container to be pulled every time, never, or only if they are not present. Valid values are Always, Never, and IfNotPresent.
     • Integration Server Pod/containers/runtime/Resource requirements: Specify resource requirements for running the runtime container. For information about the values that you can specify, see the spec.integrationServer.containers.runtime.resources.* parameters in Custom resource values.

     For information about the remaining values that you can specify, see the spec.integrationServer.containers.* parameters in Custom resource values.

   • Pod/containers/container_name: Specify settings for running the Designer containers. For information about the values that you can specify, see the spec.pod.containers.* parameters in Custom resource values.
   • Switch Server/Name: Specify the name of an existing switch server that enables secure connectivity when running callable flows in the Designer instance, or when running flows that interact with applications in a private network. The switch server name is the metadata.name value in the switch server custom resource. For information about how to create a switch server, see App Connect Switch Server reference.
     Note: If you want to create and run callable flows in the Designer instance or if you want to create flows that interact with applications in a private network, you must configure the Designer instance to use a switch server.

     • If a switch server is already deployed in the namespace, complete the Switch Server/Name field in Form view, or add the spec.switchServer.name parameter to the Designer YAML, where switchServerName is the metadata.name value in the switch server custom resource.

       spec:
         switchServer:
           name: switchServerName

       If the metadata.name value for the switch server is set to default, the Designer instance is automatically configured to use the switch server even if spec.switchServer.name is not explicitly specified. For example:

       apiVersion: appconnect.ibm.com/v1beta1
       kind: SwitchServer
       metadata:
         name: default
       ...

     • If a switch server is not yet deployed in the namespace, you can create a switch server after you create the Designer instance. Then, update the Designer custom resource to add the spec.switchServer.name setting as described in Updating the custom resource settings for an instance. (If the metadata.name value for the switch server is set to default, you do not need to explicitly add the spec.switchServer.name setting.)

       For information about how to create a switch server, see App Connect Switch Server reference.

     A Designer instance that is configured to use a switch server includes a Callable flows page and a Private network connections page that you can use to configure connectivity to callable flows and to applications in a private network.

8. Optional: For a finer level of control over your installation settings, click YAML view to switch to the YAML view. Update the content of the YAML editor with the parameters and values that you require for this Designer instance.

   To view the full set of parameters and values available, see Custom resource values.

9. Click Create to start the deployment. An entry for the Designer instance is shown in the DesignerAuthorings table, initially with a Pending status.
10. Click the Designer instance name to view information about its definition and current status.

    On the Details tab of the page, you can view the following information:

    • The Conditions section reveals the progress of the deployment.
    • If you created the Designer instance by using IBM App Connect Operator 11.2.0 or later, the Designer UI field provides the URL for accessing the Designer instance. If Keycloak is enabled, the Keycloak UI field also provides the URL of the Keycloak instance that you can use to access the Keycloak Admin Console. (These URLs are displayed after the deployment completes.) You can also locate these URLs under Networking > Routes in the console navigation.
      
    • If you created the Designer instance by using IBM App Connect Operator 11.1.0 or earlier, the UI URL field provides the URL for accessing the Designer instance. (This URL is displayed after the deployment completes.) You can also locate this URL under Networking > Routes in the console navigation.
      

    You can use the breadcrumb trail to return to the (previous) Operator details page for the App Connect Operator. When the deployment is complete, the status is shown as Ready in the DesignerAuthorings table.

What to do next

1. If IAM with Keycloak is enabled for this instance, use the Keycloak Admin Console to manage user access to the instance by setting up users with assigned roles. For more information, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
2. Share the Designer UI (or UI URL) URL with the users who need to access the Designer instance. If IAM is enabled, also supply the authentication credentials that users can use to log in to the instance.

   Users can then access and use the Designer instance to author flows.

Creating an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To create an App Connect Designer instance from the Red Hat OpenShift CLI, complete the following steps.

1. From your local computer, create a YAML file that contains the configuration for the App Connect Designer instance that you want to create. Include the metadata.namespace parameter to identify the namespace in which you want to create the instance; this should be the same namespace where the other App Connect instances or resources are created.
   • To view the full set of parameters and values that you can specify, see Custom resource values.
     
     In the default parameters that are presented, be aware that a value is required for spec.couchdb.storage.class (and for spec.couchdb.storage.size) when spec.couchdb.storage.type is set to persistent-claim. The spec.couchdb.storage.class value must match a supported storage class for your cluster.

     spec:
       couchdb:
         storage:
           class: 'storageClassValue'
           size: 10Gi
           type: persistent-claim

     IAM requirement: Keycloak requires block storage and a storage class that is set as the default class. For more information, see Storage options for Keycloak in the IBM Cloud Pak for Integration documentation.
     Note: If you want to create and run callable flows in the Designer instance or if you want to create flows that interact with applications in a private network, you must configure the Designer instance to use a switch server.

     • If a switch server is already deployed in the namespace, complete the Switch Server/Name field in Form view, or add the spec.switchServer.name parameter to the Designer YAML, where switchServerName is the metadata.name value in the switch server custom resource.

       spec:
         switchServer:
           name: switchServerName

       If the metadata.name value for the switch server is set to default, the Designer instance is automatically configured to use the switch server even if spec.switchServer.name is not explicitly specified. For example:

       apiVersion: appconnect.ibm.com/v1beta1
       kind: SwitchServer
       metadata:
         name: default
       ...

     • If a switch server is not yet deployed in the namespace, you can create a switch server after you create the Designer instance. Then, update the Designer custom resource to add the spec.switchServer.name setting as described in Updating the custom resource settings for an instance. (If the metadata.name value for the switch server is set to default, you do not need to explicitly add the spec.switchServer.name setting.)

       For information about how to create a switch server, see App Connect Switch Server reference.

     A Designer instance that is configured to use a switch server includes a Callable flows page and a Private network connections page that you can use to configure connectivity to callable flows and to applications in a private network.

     Consider whether you want to enable Mapping Assist for smart mapping and data transformation (which requires extra resources). You can also optionally enable Mapping Assist incremental learning to use AI modeling for enhanced smart mapping. If you enable incremental learning, you'll need to specify a "learning" frequency, and indicate whether the AI model should be stored in a persistent volume or an S3 bucket. If you are using an S3 bucket, you'll need to provide details for connecting to this bucket, including the name of the configuration object of type S3Credentials, which you created to store your S3 credentials. In YAML view, you can use the spec.designerMappingAssist.enabled and spec.designerMappingAssist.incrementalLearning.* parameters to configure the Mapping Assist features. For more information about Mapping Assist and the configuration object for S3 storage, see Simplifying data mapping and data transformation with AI-powered suggestions and Creating a configuration of type S3Credentials for use with App Connect Designer.

   • To control access to the instance by using identity and access management (IAM), ensure that both of these parameters are set to true (the default).
     • spec.authentication.integrationKeycloak.enabled: This setting ensures that user identities can be validated.
     • spec.authorization.integrationKeycloak.enabled: This setting ensures that access permissions can be granted.

     This value enables Keycloak, which implements IAM. For more information about using IAM with the instance that you are creating, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.

     If you do not want to restrict access to the instance, ensure that both of these parameters are set to false. Also ensure that you are using an AppConnectEnterprise* style license.

     Restriction: These settings are not applicable for Kubernetes environments.
   • For licensing information, see Licensing reference for IBM App Connect Operator.
     IAM entitlements:

     • If you purchased Cloud Pak for Integration, you are entitled to use either CloudPakForIntegration* or AppConnectEnterprise* style licenses. However, to use a CloudPakForIntegration* license, a Platform UI instance must be deployed.
     • If you purchased the IBM App Connect Operator for an independent deployment, you are restricted to AppConnectEnterprise* style licenses regardless of whether IAM is enabled or disabled. (Although installation of the Cloud Pak for Integration and other Operators is permitted for configuring IAM, you are not allowed to deploy the Platform UI.)

   The following examples (Example 1 and Example 2) show a Designer CR with settings to configure CouchDB storage, and configure an existing switch server for callable flow and private network connectivity. The settings also enable Mapping Assist and incremental learning with a persistent-claim storage definition for the AI model.

   Example 1: Keycloak enabled for IAM by default

   apiVersion: appconnect.ibm.com/v1beta1
   kind: DesignerAuthoring
   metadata:
     name: des-mapast
     labels:
       backup.appconnect.ibm.com/component: designerauthoring
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: CloudPakForIntegrationNonProduction
     couchdb:
       storage:
         size: 10Gi
         type: persistent-claim
         class: ocs-storagecluster-cephfs
       replicas: 1
     designerMappingAssist:
       incrementalLearning:
         storage:
           type: persistent-claim
           class: ocs-storagecluster-cephfs
         schedule: Every 15 days
         useIncrementalLearning: true
       enabled: true
     switchServer:
       name: default
     authentication:
       integrationKeycloak:
         enabled: true
     authorization:
       integrationKeycloak:
         enabled: true
     designerFlowsOperationMode: local
     replicas: 3
     version: '12.0'

   Example 2: Keycloak disabled - IAM not required (or not supported on Kubernetes)

   apiVersion: appconnect.ibm.com/v1beta1
   kind: DesignerAuthoring
   metadata:
     name: des-mapast
     labels:
       backup.appconnect.ibm.com/component: designerauthoring
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: AppConnectEnterpriseProduction
     couchdb:
       storage:
         size: 10Gi
         type: persistent-claim
         class: valid-storage-class
       replicas: 1
     designerMappingAssist:
       incrementalLearning:
         storage:
           type: persistent-claim
           class: valid-storage-class
         schedule: Every 15 days
         useIncrementalLearning: true
       enabled: true
     switchServer:
       name: default
     authentication:
       integrationKeycloak:
         enabled: false
     authorization:
       integrationKeycloak:
         enabled: false
     designerFlowsOperationMode: local
     replicas: 3
     version: '12.0'

   The following examples (Example 3 and Example 4) show a Designer CR with settings to configure CouchDB storage, and configure an existing switch server for callable flow and private network connectivity. The settings also enable Mapping Assist and incremental learning with an s3 storage definition for the AI model.

   Example 3: Keycloak enabled for IAM by default

   apiVersion: appconnect.ibm.com/v1beta1
   kind: DesignerAuthoring
   metadata:
     name: des-mapast
     labels:
       backup.appconnect.ibm.com/component: designerauthoring
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: CloudPakForIntegrationNonProduction
     couchdb:
       storage:
         size: 10Gi
         type: persistent-claim
         class: ocs-storagecluster-cephfs
       replicas: 1
     designerMappingAssist:
       incrementalLearning:
         storage:
           type: s3
           bucket: appc-operator-e2e
           host: s3.eu-gb.cloud-object-storage.appdomain.cloud
           s3Configuration: s3credentials-ibmcosiam
         schedule: Every 15 days
         useIncrementalLearning: true
       enabled: true
     switchServer:
       name: default
     authentication:
       integrationKeycloak:
         enabled: true
     authorization:
       integrationKeycloak:
         enabled: true
     designerFlowsOperationMode: local
     replicas: 3
     version: '12.0'

   Example 4: Keycloak disabled - IAM not required (or not supported on Kubernetes)

   apiVersion: appconnect.ibm.com/v1beta1
   kind: DesignerAuthoring
   metadata:
     name: des-mapast
     labels:
       backup.appconnect.ibm.com/component: designerauthoring
     namespace: mynamespace
   spec:
     license:
       accept: true
       license: L-QECF-MBXVLU
       use: AppConnectEnterpriseProduction
     couchdb:
       storage:
         size: 10Gi
         type: persistent-claim
         class: valid-storage-class
       replicas: 1
     designerMappingAssist:
       incrementalLearning:
         storage:
           type: s3
           bucket: appc-operator-e2e
           host: s3.eu-gb.cloud-object-storage.appdomain.cloud
           s3Configuration: s3credentials-ibmcosiam
         schedule: Every 15 days
         useIncrementalLearning: true
       enabled: true
     switchServer:
       name: default
     authentication:
       integrationKeycloak:
         enabled: false
     authorization:
       integrationKeycloak:
         enabled: false
     designerFlowsOperationMode: local
     replicas: 3
     version: '12.0'

2. Save this file with a .yaml extension; for example, designer_cr.yaml.
3. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
4. Run the following command to create the App Connect Designer instance. (Use the name of the .yaml file that you created.)

   oc apply -f designer_cr.yaml

5. Run the following command to check the status of the App Connect Designer instance and verify that it is ready:

   oc get designerauthorings -n namespace

   On IBM App Connect Operator 11.2.0 or later, the output also provides the URL of the Designer instance as shown in the following example. If Keycloak is enabled, the URL of the Keycloak instance, which you can use to access the Keycloak Admin Console, is also displayed.

   NAME                     RESOLVEDVERSION   URL                                                                                 KEYCLOAKURL                                                                  CUSTOMIMAGES   STATUS   AGE
   des-fd-keyclk-cp4ilic    12.0.12.2-r1      https://des-fd-keyclk-cp4ilic-ui-ace-fiona.apps.acecc-shared-1120-cd-414-abc.com    https://keycloak-ibm-common-services.apps.acecc-shared-1120-cd-414-abc.com   false          Ready    3h11m

   On IBM App Connect Operator 11.1.0 or earlier, the output also provides the URL of the Designer instance; for example:

   NAME         RESOLVEDVERSION   REPLICAS   CUSTOMIMAGES   STATUS    URL                                                                        AGE
   des-mapast   12.0.10.0-r3      3          false          Ready     https://des-mapast-designer-https-mynamespace.apps.acecc-abcde.icp4i.com   50m12s

What to do next

1. If IAM with Keycloak is enabled for this instance on Red Hat OpenShift, use the Keycloak Admin Console to manage user access to the instance by setting up users with assigned roles. For more information, see Identity and access management for App Connect Designer and App Connect Dashboard instances on Red Hat OpenShift.
2. Share the URL value in the output with the users who need to access the Designer instance. If IAM is enabled, also supply the authentication credentials that users can use to log in to the instance.

   Users can then access and use the Designer instance to author flows.

Updating an instance from the IBM Cloud Pak Platform UI

To update an App Connect Designer instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the Platform UI.
   • Applicable to IBM App Connect Operator 11.0.0 or later: The Platform UI Instances page opens as the home page. The welcome banner includes a theme switcher that you can use to choose a light theme, a dark theme, or a custom theme that matches your existing system UI.
   • Applicable to IBM App Connect Operator 10.1.1 or earlier: The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

     
     From the navigation menu , expand Administration and click Integration instances.

2. From the Instances (or Integration instances) page, locate the App Connect Designer (Integration design) instance that you want to update.
3. Click the options icon to open the options menu, and then click Edit. The "Edit" page opens for that instance.
4. Either use the fields in the "UI form" view or switch to the YAML view to update the required settings. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
5. Click Update to save your changes.

Updating an instance from the Red Hat OpenShift web console

To update an App Connect Designer instance by using the Red Hat OpenShift web console, complete the following steps:

1. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
2. From the navigation, click Operators > Installed Operators.
3. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
4. From the Installed Operators page, click IBM App Connect.
5. From the Operator details page for the App Connect Operator, click the Designer Authoring tab.
6. Locate and click the name of the instance that you want to update.
7. Click the YAML tab.
8. Update the content of the YAML editor as required. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
9. Click Save to save your changes.

Updating an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To update an App Connect Designer instance from the Red Hat OpenShift CLI, complete the following steps.

1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
2. From the namespace where the Designer instance is deployed, run the oc edit command to partially update the instance, where instanceName is the name (metadata.name value) of the instance.

   oc edit designerauthoring instanceName

   The Designer CR automatically opens in the default text editor for your operating system.

3. Update the contents of the file as required. You can update existing values, add new entries, or delete entries. For information about the available parameters and their values, see Custom resource values.
4. Save the YAML definition and close the text editor to apply the changes.

oc patch designerauthoring instanceName --type='merge' --patch "$(cat updatesettings.yaml)"

Deleting an instance from the IBM Cloud Pak Platform UI

To delete an App Connect Designer instance from the IBM Cloud Pak Platform UI, complete the following steps:

1. From a browser window, log in to the Platform UI.
   Tip: You can use the generated URL for a deployed IBM Cloud Pak for Integration Platform UI instance to access the Platform UI.
   • Applicable to IBM App Connect Operator 11.0.0 or later: The Platform UI Instances page opens as the home page. The welcome banner includes a theme switcher that you can use to choose a light theme, a dark theme, or a custom theme that matches your existing system UI.
   • Applicable to IBM App Connect Operator 10.1.1 or earlier: The Platform UI home page opens with cards and navigation menu options that provide access to the instances and other resources that you are authorized to create, manage, or use. For information about completing administration tasks (such as user management or platform customization) from this page, see Platform UI in the IBM Cloud Pak foundational services documentation.

     
     From the navigation menu , expand Administration and click Integration instances.

2. From the Instances (or Integration instances) page, locate the App Connect Designer (Integration design) instance that you want to delete.
3. Click the options icon () to open the options menu, and then click Delete.
4. Confirm the deletion.

Deleting an instance from the Red Hat OpenShift web console

To delete an App Connect Designer instance by using the Red Hat OpenShift web console, complete the following steps:

1. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
2. From the navigation, click Operators > Installed Operators.
3. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
4. From the Installed Operators page, click IBM App Connect.
5. From the Operator details page for the App Connect Operator, click the Designer Authoring tab.
6. Locate the instance that you want to delete.
7. Click the options icon () to open the options menu, and then click the Delete option.
8. Confirm the deletion.

Deleting an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To delete an App Connect Designer instance from the Red Hat OpenShift CLI, complete the following steps.

1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
2. From the namespace where the Designer instance is deployed, run the following command to delete the instance, where instanceName is the value of the metadata.name parameter.

   oc delete designerauthoring instanceName