CRM Customization Toolkit Guide

Scott Wallace
Scott Wallace
  • Updated

CRM Customization Toolkit Guide

Solution Overview

One of the most useful features offered by our native CRM integrations is the ability to see a lead’s Contact’s Report 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, you will still likely need to use our API in order 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:
    1. The Contact Report for a given Lead or Contact with the pages they visited, content they’ve downloaded, messages they’ve opened, and more.
    2. The Account Report for a given Account record with a consolidated view of all Contacts behaviors and account score 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 and 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. Please understand that our ability to troubleshoot implementation of these is limited and 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 
  3. Click on the Web Identity tab
  4. 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 in order 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:: 

{"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>

Note: The list ID refers to the unique ID of the target list in Act-On which contains all contact records. If you are setting up custom buttons in your CRM which has both Lead and Contact records which are stored in separate Act-On Lists, you will need to implement the button twice – once for Leads, and once for Contacts with each targeting their respective 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. 

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: 

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 activity history for the specified contact, like this: 

Contact_Report.png

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 longer or shorter depending on the length of your business’ 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, activity 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 in order 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. 

NOTE: Account Records are only available for customers:

  • Who have purchased a package which includes the Account Based Marketing module.
  • Who are syncing with Salesforce, Microsoft Dynamics or SugarCRM according to the following instructions for configuring CRM Administration

 

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

Note: When passing in the Account number from Salesforce, be sure to provide the longer, 18 character record ID for the account rather than the shorter variant.

 

Responses

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

Account_Report.png

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 login 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

There are two methods that 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 are 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.

New_Message.png

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:

Message_Error.png

After clicking OK the message editor will load, but it will display the loading graphic continuously and 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 piling 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:

Message_Report.webp

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.

 

Was this article helpful?

1 out of 1 found this helpful

Have more questions? Submit a request