Connecting Ninja Forms to Highrise
To connect to your Highrise account, you’ll need two pieces of information:
- Your Highrise Authentication token.
- Your Highrise subdomain.
Your subdomain is the phrase in your account URL. For example, if your account is http://demo.highrisehq.com The subdomain is demo
Navigate to Ninja Forms > Settings and enter these into the two text boxes found in the Highrise Section of the Ninja Forms Settings as shown here:
Your subdomain is the unique prefix of the URL you use to log into Highrise. If you log into Highrise at “myawesomecompany.highrisehg.com” , then your subdomain is “myawesomecompany”. You can find this in your Highrise account settings.
Your authentication token is found in your user settings integrations tab, as shown in this screenshot.
After entering in your Authentication Token and your Subdomain, scroll to the bottom and click “Save Settings”.
After saving your settings, click on the link named “Click to test your API connection.”
If you’ve entered valid connection settings, then you’ll now see a successful connection message in the Communication Summary. If you aren’t successful here, chances are your Authorization Token or your Subdomain are not correct.
Importing Custom Fields, Groups, Users from Highrise
If you have custom fields you intend to use, or if you use Highrise “groups” to manage your sales process, click on the “Refresh your Highrise Custom Fields List, Users, and Groups”, this will import this account data into the extension for your use later on.
Mapping Form Fields to Highrise
Once you are successfully connected to your Highrise account, you can now point all your form fields to where you’d like them to end up in Highrise.
Create Your Add to Highrise Action
After you’ve created your Ninja Form, go to the Emails & Actions tab. There you will see a button called “Add to Highrise” (arrow #1). Click this button and you will now have an Add to Highrise action added to your form as shown by arrow #2. Finally, click on the action settings (arrow #3) to start mapping your fields.
Map Your Fields
Field mapping is the process of telling Ninja Forms which information you want to send to Highrise and where in Highrise you’d like it to go.
The field map has three columns – Form Field, Highrise Field, and Location, as shown in the following screenshot. To add a new field map entry, click on the “Add New” button.
The Form Field text box specify the value from your form to use. You can use the Ninja Forms merge tags to easily specify the field value to use. In the above example, we are selected a text area.
The Highrise Field is a drop-down list of all the available locations in Highrise where you can send the data. If your Highrise account uses custom fields, these fields will appear here if you have refreshed your account data on the setting page. In this example, we are sending the text area as the body of a new Task that will be assigned to the newly created Person.
The Location field is an optional setting to specify details like “Home” “Work” “Mobile” for contact information such as phone numbers, addresses.
It is helpful to have your form design fairly complete before starting the field map but you can add or remove form fields at any time and then modify this field map to suit. When done with your field map, click “DONE” and then save your form.
Create a New Contact
To create a new contact (labeled ‘person’ because that is how Highrise specifies it), begin by mapping form fields to FirstName and LastName. After that, you can then add whatever other details from your form go with the person, such as contact information. Note how values like “Phone” or “StreetAddress” use the Location field to provide more specific information.
You aren’t limited to just form data – you can type in specific text that you wish to send.
For example, one option you can set is the visibility. You can type in Owner if you want only the authenticated user to see this new person or if you have named groups set up in Highrise, you can type in the name of the group instead.
Create a Company
The fields for creating a company are almost identical to those of a person. The drop-down options in the Highrise field column will specify “company” instead of “person” so that you can find the right one. The newly created company will automatically be linked to the new contact.
NOTE: If the company name already exists in your Highrise account, a new company will not be created and will not be linked to the new contact. This is a security issue to ensure that any person submitted the form does not have the ability to modify any of your existing account data.
If you have a specific need to modify existing data, the plugin has been designed such that a programmer can extend the code to do so (while adding the necessary safeguards to protect your data.)
Create a Deal
You can create a new deal linked to the new contact by populating the Deal fields in your field map. The PriceType, Status, and Duration fields have specific values allowed in Highrise so be sure that the value you send matches one of those.
PriceType: fixed hour month year
Status: pending won lost
Duration : Integer value
Create a Note
You can create a note for both the new person and new company. There are two fields – the body of the note and the optional “Visible to” field, which lets you specify if the note will be visible to just the Owner, Everyone, or one of your Highrise Groups.
Create a Task
You can create a task that will associated with the new person. There are two fields – the body of the task and the task time frame. The time frame can be any of these options:
Tags can be added to a person, company, or deal. You can type in the name of the tag in the form field box or you can let your form help tag the entry, typically using one of Ninja Forms’ select boxes. The screenshot shows you an example of different methods.
If you chose to use a check box, be sure to specify a value for the “checked” option, otherwise, your tag will show up as “checked” (literally). You don’t need to specify an unchecked option as the plugin is designed to ignore it. If you specify an unchecked value, then this value will be sent as the tag when unchecked.
After you have finished mapping all your fields, click ‘DONE’ and finish by saving your form. One final step will be to test your form to ensure it sends data to Highrise as intended and the best way to do it is to fill out your form and submit it. To see how it is working, after submitting your form, visit the Highrise section of the Ninja Forms Settings page. Here, you’ll see a communication summary. If your form successfully submitted, you’ll see a message saying “Successfully created at: “ along with the time.
Note that it is possible for some entries to be create but not all of them. For example, you can create a perfect Contact (named ‘person’ in Highrise) but if there is a mistake in your Deal field map, the deal won’t be created.
Don’t worry if you see an error for every entry. This will happen if there is an error with your Company or Person because if those fail, the other entries, however perfect they may be, won’t be able to attach to the Company or Person. Thus, when troubleshooting, start at the first entry that is on the Communication Summary list – it will be either Company or Person – and work your way down.
The Communication Status will guide you to solving why Highrise rejected the request. Remember that you’ve already successfully communicated with Highrise during set up so we know that your communication works and now it is just a process of ensuring your form data matches Highrise’s requirements.
Sometimes, you may not be able to figure out the issue on your own and you may feel the need to submit a support request. To help with this, we’ve built in some advanced diagnostics that will help identify the issue faster. Go to the Advanced Commands text box below the Communication Summary and type in the word support, then click Save Settings, then refresh your browser screen. After refreshing your browser screen, you will see the:
- Submission Data
- Structured Array
- Formatted Request
- Full Response
The Advanced Commands text box enables a non-developer to do some customized, more advanced commands without needing a developer. You will type in the commands you want to use, separating each with a comma, and the plugin will do the rest.
- Display the diagnostic data on a form submission. Use this when requesting support as it helps us identify and field mapping issues as quickly as practical.
- Text area boxes have html tags that are removed with code by default. If you do not wish to remove html tags before sending, add this command.
- By default, your custom fields populate the drop down field map for use in your field mapping. Should you decide that you don’t wish for these custom fields to be displayed, use this command to disable them.
- Display your custom fields, users, and groups on the settings page. A little added convenience if you want to see these values without having to log into Highrise to look them up.
- If you wish to have a developer write custom processing functions, this code will enable the use of the custom process. Using this code lets you turn on and off the custom processing quickly without having to touch code or disable the custom plugin.