CRM Customization Toolkit Guide

Solution Overview

One of the most useful features offered by our native CRM integrations is the ability to see your lead’s Contact Reports directly. You can get insight into their interests and pain points based on web pages they've visited, content they've downloaded, search terms they’ve used, and much more. Another great feature is the ability to quickly send personalized emails to any lead or contact in the CRM, & then track whether those messages are opened or clicked to analyze engagement and success.

Our Toolkit brings these two powerful abilities to your own custom CRM or other application. Your Sales team will be able to see the details and timeline of an individual’s recent activity, and quickly send an Act-On message to any lead or contact, without leaving your platform.

Using a set of JSPs (Java Server Pages), developers can bring the Act-On Contact Report and mailing capabilities directly into their platform. These JSPs can greatly simplify the creation of an Act-On integration, reducing the number of API calls needed to get reporting data or trigger email messages.

Please note that you will still likely need to use our API to retrieve information like list and record IDs, or to perform additional tasks like updating field values in Act-On. You can find more information about our API or sign up for a Developer account here.

What’s Included

The toolkit consists of three JSPs. These can be implemented in a variety of CRMs and server platforms.

1. Login JSP: This allows the user to connect to your Act-On account from within your CRM for a seamless connection to the other JSPs below.
2. Activity History JSP: This allows you to request:
   • The Contact Report for a given Lead or Contact with pages they visited, content they’ve downloaded, messages they’ve opened, and more.
   • The Account Report for a given Account record with a consolidated view of all Contact's behaviors & account scores for customers who have purchased a package including the Account Based Marketing module.
3. Send Message JSP: This opens the Act-On message editor in a standalone window to create & send a message that will be tracked in the recipient’s Activity History.

While we are happy to provide these solutions as options, a developer will likely be needed to implement them. Our ability to troubleshoot the implementation of these is limited & will also require the cooperation of your developer. However, we have included some FAQs for each JSP below to address common issues.

Getting Started

Find Your Act-On Account’s Default URL

JSP requests must be directed to your Act-On account server. As a result, the first step to using this Toolkit is to locate the exact URL for your account’s default marketing domain.

1. Log in to your Act-On account directly.
2. Go to Content > Branding > Web Identity tab.
3. Select and copy the default Marketing domain.

Example URLs

• Login URL
  https://<Default Marketing Domain>/acton/api/extLoginAjax.jsp
  → https://a14074.actonsoftware.com/acton/api/extLoginAjax.jsp
• Contact Report (Activity History) URL
  https://<Default Marketing Domain>/acton/api/extActivityHistory.jsp
  → https://a14074.actonsoftware.com/acton/api/extActicityHistory.jsp
• Send Email URL
  https://<Default Marketing Domain>/acton/api/extSendEmail.jsp
  → https://a14074.actonsoftware.com/acton/api/extSendEmail.jsp

Login JSP

The Login JSP is not required to use either of the other JSPs in this toolkit, but it will provide a more seamless experience for the end user. If the login JSP is not used and the end user’s browser is not currently authenticated to the Act-On account, they will be prompted to enter their username and password. The Login JSP can also be used to set authentication cookies for a user without using the other JSPs.

Making the Call

Requirements

There are a few requirements for making a successful login call:

• Must be done over SSL (the URL has to start with https://).
• Use HTTP POST.
• The username and password parameters must be included.

Parameters

The POST method takes two parameters in the request body: n=username and p=password.

Simplified example:

POST: https://a14074.actonsoftware.com/acton/api/extLoginAjax.jsp In the request body:

n= name@company.com
(Act-On username)

p=*******
(Act-On Password)

Responses

If your credentials are correct, the JSP will return a success message, along with the authentication cookie (with a set cookie header) in the response. The message will be a JSON string that looks like this:

{"status":"ok","protocol":"http","a":#####,"u":#####}

Note: “a” is your account’s ID number, and “u” is your user ID number. The cookie name is “uc”.

Incorrect credentials will return a message like this:

{"protocol":"http","code":402,"domain":"ci##.actonsoftware.com","message":"Login failed. Please try again.","status":"error"}

Once the cookie is established in the browser, calls to the Activity History and Send Message JSPs will use the cookie to verify authentication instead of prompting for a login.

Note: If this request is being made server-side, rather than from the browser, the server will need to store the cookie provided in the response and pass it to the browser for the browser to be authenticated.

Sample Login HTML

<html>
<body>
<form method="post" action="https://<Default Marketing Domain>/acton/api/extLoginAjax.jsp" accept-charset="UTF-8">
  Login: <input type="text" name="n"/>
  Pass: <input type="password" name="p"/>
  <input type="submit"/>
</form>
</body>
</html>

To test, save this code as an HTML file and open it in a browser. Fill in the login form and click submit. This will set the authentication cookie on your browser.

Login JSP FAQ

I’ve logged in successfully, but the Send Message/Activity History JSP is giving me an authentication error. Why?

This behavior is sometimes seen when posting using a server-side request. The authentication cookie is being returned but is being set on the server itself instead of in the user’s browser. This has been solved in the past by using a script to parse the authentication cookie from the response and pass it along to the browser.

My Default Marketing domain is foo.actonservice.com not foo.actonsoftware.com. I see the “uc” authentication cookie being set but when I redirect the user to Act-On they are not logged in. Why?

If your Default Marketing URL is in the actonservice.com domain, you’ll need to redirect the user to https://aXXXX.actonservice.com/acton vs. redirecting them to the server’s https://ciXX.actonsoftware.com/acton hostname.

Activity History JSP (Contact Report)

This JSP will open the Contact Report, which contains the behavior and activity data associated with the specified email address, as well as the contact’s lead score. For information on opening the Account Report instead, see below.

Making the Call

Requirements

There are a few requirements for making a successful call:

• Must be done over SSL (the URL has to start with https://).
• Depending on your configuration, you may need to target the call to a new window (popup), rather than the same page.
• Parameters are passed in encoded form via the URL.

Parameters

The parameters for the Activity History JSP are:

• email=<URL Encoded Email Address>
• listid=<Act-On list id>

“URL Encoded” means that spaces and special characters are replaced with an encoded version. The @ symbol is encoded as %40, while spaces are written as %20.

For example, for a contact with the following information:

Email = example@domain.com
Listid = l-1ac9e8

This query string would be used to display their activity history:

?email=example%40domain.com&listid=l-1ac9e8

The full URL should look like this:

https://a14074.actonsoftware.com/acton/api/extActivityHistory.jsp?email=example%40domain.com&listid=l-1ac9e8

Responses

If successful, the JSP will display the Contact Report with the activity history for the specified contact, like this:

If the email address value is not a correctly formatted email address (such as missing the @ symbol or containing a space) you will see a 403 error.

Contact Report (Activity History JSP) FAQ

Where can I find the list ID of a particular list?

The listid is the unique identifier for the list. You can get the list IDs for all lists in your Act-On account by using the ​Get List of Assets endpoint.

You can also get a single list ID directly from Act-On. Open the list whose ID you want to find, then hover over the list’s name in the top left corner. Right-click on the name and choose ‘View frame source’. You will see the ‘id’ parameter in the URL bar of the source window.

I looked up an email that doesn’t exist in my Act-On account, and it still displayed that Activity History window. What happened?

If you are looking up an email address that did exist once, but has since been deleted from your lists, the Activity History will still display any activity values associated with that email address.

The Behavioral Score is much lower than it should be for the number of emails opened/pages viewed/forms submitted by this email address. What causes this?

Act-On Scoring Rules can be restricted to a certain period of time - typically 90 days, but this can be set for longer or shorter depending on the length of your business’s sales cycle. Only activity that has taken place within that period of time will count for the current score.

If your Scoring Rules are set to only use the last 90 days, activities that occurred more than 90 days ago will not receive any points. You can change your scoring timeframe at any time by logging into Act-On directly and going to Contacts> Scoring Rules. Changes will register as soon as you refresh the Activity History window.

Activity History JSP (Account Report)

The same Activity History JSP can also be invoked to open the Account Report, which contains the behavior and activity data associated with the specified account record, as well as the account’s score.

Making the Call

Requirements

There are a few requirements for making a successful call:

• Must be done over SSL (the URL has to start with https://).
• Depending on your configuration, you may need to target the call to a new window (popup), rather than the same page.
• Parameters are passed in encoded form via the URL Parameters:

Parameters

• account=<account number from your CRM>

Example:

An Account with the following information:

Account number = 123456789

This query string would be used to display their activity history:

?account=123456789

The full URL should look like:

https://a14074.actonsoftware.com/acton/api/extActivityHistory.jsp?account=123456789

Responses

If successful, the JSP will display the Account Report for the given Account, like this:

Send Message JSP

This JSP will open the Act-On Message Editor, with the message addressed to one or more specific recipients.

Making the Call

Requirements

• Must be done over SSL (the URL has to start with https://).
• The call should be in a new window (popup), rather than the same page.
• The call will require the user to log in if no cookie is established, otherwise, an active valid user login cookie will be honored (i.e. the cookie established via the Login JSP).
• Messages can only be sent to specific users, selected via the parameters described below:

Parameters

Two methods can be used with this JSP to identify the individual contacts.

REC ID METHOD

If you are using the API to get the record IDs of specific contacts you can use the ‘recid’ parameter. Each record ID will be in the format returned via the API (e.g. l-0001:345), and individual IDs will be separated by semicolons.

?recids=<recid1>;<recid2>;<recd3>

The full URL will look like:

https://a14074.actonsoftware.com/acton/api/extSendEmail.jsp?recids=l-0001:12;l-0001:13;l-0001:52

LIST ID/EMAIL METHOD

If you do not have the specific record IDs, you can use the list ID in combination with the email addresses you want to send to instead. These parameters are ‘listid’ and ‘emails’. Each email address must be URL encoded, and separated by semicolons.

?listid=<listid>&emails=<URL encoded email 1>;<URL encoded email 2>

The full URL will look like:

https://a14074.actonsoftware.com/acton/api/extSendEmail.jsp?listid=l-0001&emails=example%40domain.com;example2%40domain.com

Responses

If successful, the Message Editor window will load.

If the record IDs are missing or incorrectly formatted, or if the email address does not exist in the list specified, you will get the following error pop-up:

After clicking OK the message editor will load, but it will display the loading graphic continuously, & clicking any of the starting options will have no effect.

Using the Send Message JSP

Creating a Message

The Send Message JSP uses the same editor available within Act-On directly and the majority of functions are available.

There are, however, several restrictions:

• The Address tab will only display the recipients selected via the parameters in the URL.
• Additional recipients cannot be added from within the UI - they must be added via the URL parameters.
• It is not possible to change the From and Reply-To addresses - it will use the information for the email address that was used to authenticate in the Login JSP.
• The message cannot be saved as a Draft (this is to prevent large numbers of unfinished messages from building up).

Viewing the Message Report

Messages sent via the JSP are counted as ‘messages to specific people’. To view the Reports for these messages in Act-On, you will need to make sure that “Hide Messages to Specific People” is unchecked. This setting can be found in the upper left corner of the Outbound > Sent Messages area:

Send Email JSP FAQ

I want to send to more record IDs than can fit into a query string. What can I do?

If a large number of parameter values are needed, and go beyond query length limitations, you can change the call to POST instead of GET. This should allow you to submit arbitrarily long parameter values.

Where can I find the recids for a set of contacts?

The recid is a unique identifier returned for each contact in a list. You can use the Download a List API endpoint to get the record IDs for all contacts in a particular list.

For testing purposes, you can also get the record ID from Act-On directly. Open a list containing the contact you wish to use, and click on their row in the list to bring up the Contact Report. The record ID will be the ‘cid’ value from the URL.

Where can I find the list ID of a particular list?

The listid is the unique identifier for the list. You can get the list IDs for all lists in your Act-On account by using the Get List of Assets endpoint.

For testing purposes, you can also get a single list ID directly from Act-On. Open the list whose ID you want to find, then hover over the list’s name in the top left corner. Right-click on the name and choose ‘View frame source’. You will see the ‘id’ parameter in the URL bar of the source window.