String Manipulation Cloud App

This Document will describe the String Manipulation Cloud App, and how to use it within your instance of Eloqua.

Advanced users of marketing automation software like Eloqua sometimes find themselves in a situation where they need to manipulate string data. This can be as simple as trimming the space characters from the start or end of a string, or detecting whether a value exists in a string.  It can also be as advanced as search and replace, or even complex Regular Expression work.

The String Manipulation Cloud App allows you to do just that - any form of string manipulation - within Eloqua.

In order to use the App, you must be registered at cloudconnectors.eloqua.com.  When creating your account, make sure the user whose Eloqua credentials you provide is added to the “API Users” security group to ensure it has API access.  Your Eloqua administrator will have to do this for you.

What is the difference between Appcloud.eloqua.com and Cloudconnectors.eloqua.com?

String Manipulation Cloud App Components

The String Manipulation Cloud App consists of the following Cloud Connector:

• String Manipulation: allows you to use Regular Expressions or Trim functions to manipulate any strings.

ARTICLE – What is the difference between an App, a Connector, a Component and a Feeder

Installation and Configuration

To install the String Manipulation Cloud Connector in Eloqua, do the following.

Log into cloudconnectors.eloqua.com and click on the Apps menu.

Click on String Manipulation, and the following screen will appear:

Click on Install Connector.  You'll then be shown the installation screen.

If you are an Eloqua administrator, you can click on Add Connector, and it will take you to the Cloud Connector Management area in your instance, with the install settings pre-populated.

You can also choose to do a Manual Install (note the settings above) and then go into the Cloud Connector Management are in your instance.  Enter the settings as shown below.

Enter the following information:

• Service Name:  String: Manipulation
• Service URL: https://cloudconnectors.eloqua.com/StepAdmin/AutomatedStepOverview.aspx?StepID={STEP_ID}&Company={COMPANY}&stepType=StringManipulateContact
• Unique Id: StringManipulateContact
• Click the Add button

If you receive a confirmation similar to this, the Connector has successfully been installed:

To configure the App, do the following:

• Add a step to your marketing automation program at any point you would like to manipulate string values within contact records.
  • Note: The Cloud Connector will allow you to manipulate the string data, in any one contact field for all contacts that flow through this step, and either return the data to that same field, or place it in another field.
  • Make sure that you have an account on cloudconnectors.eloqua.com.
  • Drag a "Send to Cloud Connector" step onto the Canvas from the toolbar:

Double-click on the "Send to Cloud Connector" step, select String: Manipulation from the list, and click on the configuration button.

When the Login screen appears, enter your cloudconnectors.eloqua.com credentials and click Log In.

Next the first setup screen for the App will appear.

The values for Eloqua Client Name and Program Builder Step ID will automatically populate.  Enter the remaining information, then click Go.

The configuration page will then be displayed.

On the Configuration tab, enter the following information:

• Description (optional):  Some text about this connector instance
• String operation: The string operation to perform on the contact field.  These include:
  • String Find: Looks for an exact string that you input (not case sensitive), and returns a value of your choosing.

The following additional fields are displayed for this option:

• Text to find: The text to look for in the contact field
• Text if found: The text to write back tot he Returned Value field if the Text to find is found
• Text if not found: The text to write back tot he Returned Value field if the Text to find is not found
• String Replace: Looks for an exact string (not case sensitive), replaces that string with another string that you provide, and returns the final edited text.
  • Note that if the pattern is not found, the string returned is the original string

The following additional fields are displayed for this option:

• Text to find: The text to look for in the contact field
• Text to replace: The text to write back to the Returned Value field in place of the Text to find

• Regular Expression Find: Evaluates a regular expression (RegEx) against the string in the contact field and  and returns a value of your choosing.

The following additional fields are displayed for this option:

• Regular Expression to find: The Regular Expression to evaluate for the contact field
• Text if found: The text to write back to the Returned Value field if the Regular Expression to find is found
• Text if not found: The text to write back tot he Returned Value field if the Regular Expression to find is not found
• Regular Expression Replace: Evaluates a regular expression (RegEx) against the string in the contact field and then replaces it with the string or Regular Expression you provide. This allows replacing a string with a derivative of itself (ie, replacing any number with "(#)" where # represents the original number.
  • Note that if the pattern is not found, the string returned is the original string

The following additional fields are displayed for this option:

• Regular Expression to find: The Regular Expression to evaluate for the contact field
• Regular Expression replace: The text to write back to the Returned Value field based on the evaluation of the Regular Expression to find

• Trim (Left/Right/Full): Trims the whitespace from the front, end, or both of a string
• To Lower Case: Converts the string to lower case
• To Upper Case: Converts the string to upper case
• To Title Case: Converts the string to title case
• NOTE: Use the help provided for syntax assistance on how to write Regular Expressions.
• Click Save Settings.

Next, click on the Mappings tab.  The Mappings screen will then appear.

On the Field Mappings tab, choose the following:

• Email Address:  The contact field that holds the Email Address.  This is used to identify the contact record to operate on.
• Input String:  The contact field that holds the string you wish to manipulate.
• Returned Value:  The contact field to write the new (manipulated) string back to.
• Click Save Settings.

You are now ready to Test the connector to make sure all is set correctly.  Click on the Test tab.

Once your step is enabled and running, the Step Members testing tab will show you the counts of contacts in your step.

The Run Manually testing tab will allow you to perform a Dry Run or a Full Run of your step.  A Dry Run will simulate a run, but will not actually write the data back to Eloqua.  A Full Run will perform a run of your connector, actually updating Eloqua.

Use the Sample Data tab if you wish to test your setup on select contacts.  Enter their email addresses, one per line, and click Test Contacts. (Note: these contacts must already exist in your instance).

If you check the Full Run box, the data will be written to Eloqua, if left unchecked, it will simulate the connector and show you the results.

To check the history of your step execution, click on the History tab.

Now that you have tested your step, it's time to enable it.  Click on the Credentials tab.

When you are ready to enable your step (remember to also enable your program in Eloqua) click the Enable Step button.

With the step running automatically, any contacts that flow into the step will have the field you specified manipulated.