You can use the Connect Cassandra rule to connect to external Cassandra database clusters that contain an established data model. With this rule, you can use your existing data model and reflect it in the Pega 7 Platform by mapping the database properties to the Pega 7 Platform properties or by creating properties. To perform database read or write operations with Connect Cassandra rules, you must call these rules from activities in your application.

Creating Connect Cassandra rules

Follow these steps to create a Connect Cassandra rule that supports read or write operations on an external Cassandra database cluster from your application.

Prerequisites

Before you can connect to a Cassandra database cluster, upload the Cassandra client JAR file that corresponds to the version of Cassandra that you are using.

1. In the Records Explorer, expand the Integration-Connectors list.
2. Right-click Connect Cassandra and click +Create. On the Create form, provide the following information for the new rule:
   1. Enter the rule label.
   2. Specify the ruleset, Applies To class, and ruleset version.
   3. Click Create and open.
3. Configure the connection to the Cassandra database.
4. Map the table columns in the Cassandra database to properties.
5. Reference the Connect Cassandra rule from activities to write or read from the Cassandra database.

Configuring the connection to the Cassandra database

Configure the basic connection and authentication settings on the Services tab of the Connect Cassandra rule form.

1. Click the Services tab.
2. In the Connection section, enter the following information:
   • Host – Enter the server IP address of the Cassandra cluster.
   • Port (Optional)– Enter the port of the Cassandra cluster. The default port is 9042.
   • Response timeout (Optional) – Enter the number of milliseconds after which, if no response is received, this rule times out with a failure message. Enter zero or leave blank to wait indefinitely.
3. Optional: To establish a secure connection with the Cassandra cluster, configure the authentication settings:
   1. In the Authentication section, select the Use authentication check box.
   2. In the Authentication profile field, press the Down Arrow key and select an instance of an authentication profile rule that contains details that are required by the remote service. For example, a user name and a password that are used for basic authentication.
4. Optional: To protect data in transit between database clusters and to prevent unauthorized access to database clusters, configure the security settings:
   1. In the Security settings section, select the Use secure connection check box.
   2. In the Truststore field, select a Cassandra cluster truststore that verifies user credentials when connecting to the cluster, or click the Open icon to create one.
   3. In the Keystore field, select a Cassandra cluster keystore that provides user credentials when connecting to the cluster, or click the Open icon to create one.
      For detailed steps on how to create truststore and keystore records, see the Cassandra documentation.
5. Optional: To facilitate detection and repair of problems with connecting to the Cassandra cluster, configure error handling settings by entering values in the following fields:
   • Status value property – Select a property to store the status code of the Connect Cassandra rule.
   • Status message property – Select a property to store status descriptions or return values from the external system that are returned by the Connect Cassandra rule.
   • Error handler flow – Select a flow instance that routes blocked work items when this rule is unable to connect to the external system. The default ConnectionProblem flow provides an approach for handling connector exceptions.
6. Optional: Configure the processing options to allow the connector requests from this Connect Cassandra rule to be processed in parallel with the calling activity or in the background process by an agent:
   • Intended for:
     • Immediate execution – The connector runs synchronously; the calling activity waits for results.
     • Queuing (response will not be available) – The connector runs asynchronously, with calls placed in a queue. The calling activity continues without waiting for results.
   • Requestor processor – If you selected Queuing in the Intended for list, select a Connect Request Processor data instance in this field that defines the classes and other characteristics of the queued connector request.
7. Optional: Click Test connectivity. The Pega 7 Platform verifies the connectivity by constructing the URL based on the host and port settings.
8. Optional: Click Simulations to create a connector simulator for this rule.

Mapping the tables in the Cassandra database to properties

When you establish the connection between your application and an external Cassandra database, you must map the Cassandra database tables to application properties. Create new properties if no existing properties match columns in the Cassandra database. Follow this procedure to create a data model in your application that reflects the structure of an existing Cassandra database.

Prerequisites

Before you map tables to properties, ensure that a working connection between your application and the Cassandra database has been established.

1. On the Connect Cassandra form, click the Mappings tab.
2. Define the source for property mapping by performing the following steps:
   1. In the Mapping source section, select from the Keyspace list a keyspace that is defined in the Cassandra database.
   2. In the Table name list, select a Cassandra database table that is defined for the keyspace that was selected in the previous step.
3. Set the property mapping by performing the following steps:
   1. In the Data mapping section, click +Add mapping.
   2. In the Cassandra column box, enter the name of a column in the Cassandra database.
   3. In the Property name field, press the Down Arrow key and select a property to map to the Cassandra column.
   4. Repeat steps 3a through 3c to map more columns to properties.
4. Click Save.

Mapping properties from the Cassandra database

Referencing Connect Cassandra rules in activities

You can use activities to start a connector to read from or write to external Cassandra databases. Activities automate work in your application by running a set of steps that you define.

1. In Designer Studio, click +Create > Technical > Activity.
   Instead of creating activity rules, you can reference a Connect Cassandra rule in one of your existing activities by adding additional steps.
2. On the Create form provide the rule details:
   1. Enter the rule label.
   2. Specify the ruleset, Applies-to class, and ruleset version.
   3. Click Create and open.
3. In the step that you want to call a Connect Cassandra rule, fill in or configure the following fields:
   • Method – Select Connect-Cassandra from the list of available methods.
   • Step page – Optional: If you need a context that is different than the primary page, identify a page to be used as the context for referenced properties within the step.
   • Description – Optional: Enter text that explains the action that the step performs.

     

     Creating activities that call Connect Cassandra rules

4. Configure the Connect-Cassandra method parameters:
   1. Click the right-arrow next to the Method box.
   2. Configure the following parameters:
      • ServiceName – Enter the name of the Connect Cassandra rule to call when this step runs.
      • ExecutionMode – Select an option to indicate how the Connect-Cassandra method runs. Options include:
        • Run – Runs the connector synchronously (default). The next step of the activity containing the Connect-Cassandra method does not run until the connector response is received.
        • Run in Parallel – The connector runs in parallel as a child requestor of the current requestor. For this option, use the Connect-Wait method in a subsequent step or in a follow-on activity to access the results from the connector. By default, an invoked connector retains control of the requestor session until it returns a response. Select this option if you want the connector to return control of the session directly after completing the request without waiting for a response.
        • Queue – Adds the connector request to a queue, which is defined by a Connect Request Processor data instance, for background processing by the Pega-IntSvcs ProcessConnectQueue agent.
      • EndPointURL – Optional: Enter the URL of an external system to which you want to connect. The value of this parameter overrides the value set in the Connection settings of the Service tab of the Connect Cassandra rule.
      • Operation – Select the type of HTTP request:
        • Get – Retrieves data from the Cassandra database.
        • Put – Writes data to the Cassandra database.
5. Perform the following steps only if you selected Put as the type of HTTP request for the Connect-Cassandra method:
   1. Click the Parameters tab.
   2. Create a parameter for each property defined in the Data mapping section of the Connect Cassandra rule that you refer to in the ServiceName field. Use the notation Param.<ParameterName> to enter a parameter value, for example, Param.age.
   3. Click Save.

In this tutorial, you established a connection between your external Cassandra database and the Pega 7 Platform by creating a Connect Cassandra rule. You created a Pega 7 Platform data model that reflects the data model in the Cassandra database by mapping and creating properties. Finally, you created an activity that calls the Connect Cassandrarule to read or write data to the Cassandra database.