The Real Magnet iMIS integration is a .NET Web Service which serves as a query endpoint for various contact groups in iMIS. The web services are based on the .NET iMIS Business Objects, and you must be licensed for the iMIS Business Objects by ASI. The iMIS Business Objects will work with iMIS 10.x or greater.
Watch the Video
Who should read this guide?
This guide is for Real Magnet users responsible for determining messaging and contact management guidelines. It assumes that you are familiar with:
- Using the Real Magnet system
- Managing Users in iMIS
- Managing Data within iMIS
Failure Notifications
Whenever there is a failure for the integration, an individual can opt-in to receive a daily notification.
To modify this setting:
- Log in to Real Magnet.
- Select iMIS Management.
- Select Settings.
- Under Failure Report, ensure that Enabled is set to YES.
- Enter a Run Time.
- Enter the email address(es) (comma separated format).
- Click Save.
User-Access Requirements
A Real Magnet account administrator can designate what users in the account have permission to access the integration. Below you will find tables detailing what each permission level means and what a user can do with that permission.
To assign a permission:
- Select Tools.
- Select Account Management.
- Select Integration Access Levels.
Real Magnet User Permissions
Scheduled Upload
| Permission Level | View | Run | Create/Schedule | Edit | Delete |
|---|---|---|---|---|---|
| Full Access | Y | Y | Y | Y | Y |
| Read Only | Y | Y | N | N | N |
| No Access | N | N | N | N | N |
NOTE: In order to use Sync on Send, a user must at least have access to Read Only Permission Level for Scheduled Uploads.
Tracking
| Permission Level | View | Edit |
|---|---|---|
| Full Access | Y | Y |
| Read Only | Y | N |
| No Access | N | N |
Configuring Tracking Information in the Real Magnet Account
As a default, no tracking information is selected to push over to the production environment. In order to select what tracking information is pushed to iMIS, and when, an administrator must log in to Real Magnet.
Real Magnet recommends that full access over manage tracking be a permission granted only to other administrators. Once tracking information has been selected, Real Magnet will only sync records with iMIS from that point onward. It is for this reason that access to this panel should remain limited.
NOTE: This page also provides detailed error descriptions in the event any records have not synced the night before.
To enable tracking, log in to Real Magnet, and then:
- Select Tools.
- Select iMIS Management.
- Select Manage Tracking.
- Select the Tracking items to sync to the iMIS.
- Select the time you would like for this information to come over.
NOTE: With any integration platform, there is a known use of data; for this reason, Real Magnet recommends that the data be sent over in off-peak hours.
Options for tracking data that can be returned to iMIS include:
- Email Delivered
- Opens
- Click-throughs
- Unsubscribes
- Subscribes
- Suppressed
- All Bounces
- Soft Bounces
- Hard Bounces
- User Not Found Mailbox Full
- Bad Domain
- Temporarily Unavailable
- In Progress
- Send Failed
- Fax Sends
- SMS Sends
- Event Signups
- Survey Submissions
- Landing Pages Submitted
- Website Visits
- Goal Reached
Considerations before Uploading iMIS Queries, Views, or Committees
Uploading recipients from the iMIS interface to Real Magnet can be performed in a variety of ways. Below are the considerations that must be made before you upload your first query from iMIS.
Unique Identifiers
Every database-driven system has a way to enforce uniqueness on records to avoid duplicates. Real Magnet offers two options for determining uniqueness:
- Email address
- iMIS Contact ID (custom member ID)
NOTE: These choices assume that there is a Real Magnet integration installed (e.g., netFORUM or Aptify). The default setting has the recipient’s email address as the unique ID.
Email as a Unique ID
When this default option is enabled, Real Magnet will only create one record for any single email address. For every record uploaded to Real Magnet that contains a custom ID and an email address, Real Magnet will create a unique record based on that email address.
NOTE: There can be NO duplicate email addresses with this method.
Implications
- Email addresses cannot be overwritten from iMIS
Custom Member ID as a Unique ID
When custom ID is selected as the unique identifier, this will be generated by the unique identifier supplied with your AMS or API process. In the case of iMIS, this is the Contact ID.
Implications
- Every record uploaded to Real Magnet must contain an iMIS Contact ID
- Duplicate email addresses can exist
- Email addresses can be overwritten from iMIS
Replacing Real Magnet Records
Real Magnet provides two options when uploading a Saved Search:
- Adding recipients - If add to existing list is selected, Real Magnet will only add the records to the group with the records from the upload. Individual records will not be updated or overwritten.
- Replacing recipients - If Replace existing list is selected, Real Magnet will replace the records in the group with the records from the upload. The records being removed are not deleted, only removed from the group (they remain in the database), and there is no impact on the historical data.
NOTE: The replace method can be made the default. To do so, submit a request to your Implementation Project Manager or to Support.
If Replace is selected (Real Magnet’s default setting to overwrite existing data), based on the unique identifier will overwrite the corresponding data that exists in Real Magnet. This can be particularly useful in instances where there is one database of record that is in the process of being constantly updated.
NOTE: Add to Group will not update individual records in Real Magnet.
Character Limitations
When uploading a list to Real Magnet, the maximum characters allowed per field are:
| Field Type | Characters |
|---|---|
| E-mail, Address 1, Address 2, All Custom Fields | 100 Characters |
| First name, Last Name, Phone, Fax, City, State, Zip | 50 Characters |
| Company | 200 Characters |
| Enhanced Personalization Field | 250 Characters |
Uploading iMIS Recipients to Real Magnet
All individual queries that are transferred from iMIS to Real Magnet are referred to as an upload job. Upload jobs that are allowed via the integration:
- SQL Views must contain:
- A field called ContactID that is the iMIS ID of the persons record
- Email address
- Adhoc Queries must contain:
- The ContactID
- IQA Queries must contain:
- A field called ContactID that is the iMIS ID of the person's record (See Adding iMIS IQAs to the Real Magnet Groups Table)
- Email address
- Committees:
- These lists must be active
- The Real Magnet settings table must have auto-create set to true
Transferring Lists from iMIS to Real Magnet
Data can be transferred from iMIS to Real Magnet via a scheduled upload or one-time transfer from within Real Magnet. To do so, that query or list must first be added to the Real Magnet Groups table.
Adding Queries to the Real Magnet Groups Table
The Real Magnet Bridge uses the fields’ code and description from REALMAGNET_GROUPS table. To expose an existing query to the Real Magnet Upload tool:
- Click Set Up Tables.
- Click General Lookup/Validation.
- Select REALMAGNET_GROUPS from the menu.
- Select New.
NOTE: Ignore the field labeled Expansion.
- Enter the values for Code and Description:
- Code - Group Name
- Description - Location (technical name of the group), and there are three options: (1) Adhoc Query Name (e.g., TEXAS_MEMBERS); (2) SQL View (e.g., TEXAS_MEMBERS_VIEW) *Note that dbo is not included in this. The Real Magnet groups table only requires the name of the view.* (3) IQA Query path (e.g., $/ContactManagement/DefaultSystem/Queries/Advanced/Contact/Other/Top Donor) (See Adding iMIS IQAs to the Real Magnet Groups Table).
The data you enter here is the listing of iMIS contact groups you wish to query using the Real Magnet Upload Scheduler. The groups used by the Real Magnet can exist in iMIS, and as a view in your iMIS database.
Scheduled Upload
The Real Magnet Upload Scheduler (RMUS) is a feature of the integration that allows for automated uploads to the Real Magnet system; it is extremely useful in the event there are any Saved Searches that you send to on a regular basis.
It allows the following upload job types:
- Run Now - This upload job will run once. Once completed, edits or changes cannot be made to this upload job.
- On Demand - This upload job will only run when the green play icon is clicked or using the Sync on Send functionality. This will deploy the upload job when a message is scheduled to send to the group attached to the upload job.
- Scheduled - This upload job will run on a scheduled basis, either daily or weekly, and can be manually run by clicking the green play button. When selecting a group connected to an active Marketing Automation campaign, this option can also upload groups on an hourly basis.
The RMUS can be accessed by logging into Real Magnet and selecting Tools. The details below will cover all aspects of the RMUS.
Icon Legend
| Icon | Description |
|---|---|
 |
Delete the upload job. |
 |
Edit the upload job. This function only applies to On Demand and Scheduled jobs. |
 |
Run job. This function only applies to On Demand and Scheduled jobs. |
 |
View the rejected individual records (Real Magnet validates all email addresses uploaded to Real Magnet). |
Upload Jobs Page Overview
This page contains a list of your existing upload jobs in the Real Magnet platform, you’ll see a list of the existing upload jobs, and it will contain the following:
- Group Name - The name of the individual query from iMIS.
- Date Created - The date the upload job was created.
- Job Type - Whether the job is Run Now, On Demand, or Scheduled.
- Frequency - The frequency of the scheduled job, for Run Now and On Demand this will remain blank
- Scheduled time - The times the job has either completed or is scheduled to run next.
- Start Time (HH:MM) – The time the upload job is scheduled to start.
- Last Run (MM/DD/YYYY HH:MM) – The time the upload job was last executed and completed.
- Next Run (MM/DD/YYYY HH:MM) – The next scheduled time it is set to run.
- Group Results - The group in Real Magnet the query was uploaded to and the results of the last upload, that includes the total number in the group and the number added. Any error that may occur on upload will surface here.
- Actions - The allowed actions a user can make to the upload job.
Create an Upload Job
To create an upload job in Real Magnet:
- Select Tools.
- Select iMIS Management.
- Select Create Upload Job.
- Select an IQA, Adhoc Query, SQL View, or Committee.
- Select Create Map.
- Select View Entire Field List or One by One.
- Select which columns you would like to bring over to Real Magnet. These are a one-to-one relationship when mapping fields. This means that you can only map the fields on the left side of the screen with one item on the Real Magnet side once.
- Click Create Schedule.
- Select Create New Group or Add to Existing Group.
- Select either Add to existing group or Replace existing list.
- Depending on account settings the third upload step may reveal the option whether or not to update. Select Do not Update Existing Records (Only Add Records To Group) or Update Existing Records.
- Click Create.
- Select your frequency: Run Now, On Demand, or Scheduled.
- Click Submit.
Manually Upload Communities to Real Magnet
When uploading a list independent of the RMUS for tracking information to report back to iMIS, a user must include the ContactID and email address. Upon upload, the user must map the ContactID column to the Custom Member ID field in Real Magnet.
| Field Type | Characters |
|---|---|
| E-mail, Address 1, Address 2, All Custom Fields | 100 Characters |
| First name, Last Name, Phone, Fax, City, State, Zip | 50 Characters |
| Company | 200 Characters |
| Enhanced Personalization Field | 250 Characters |
Real Magnet Data in iMIS
The only information to report back to iMIS is the tracking results of a message. This tracking information will update once per day.
Viewing Tracking Data in iMIS
On the Customers > manage customer’s page, click the RealMagnet tab.
The tab will contain the following details:
- ActivityCode and ActivitySubcode (see Activity Codes and Subcodes)
- EmailAddress - The email address of the iMIS contact.
- RecipientID - The Real Magnet Recipient ID.
- DateStampUTC - The date the activity took place.
- CategoryName - Based on your unsubscribe settings this will report back either the Real Magnet group or message category name.
- GroupName - The Real Magnet group name.
- MessageName - The Real Magnet message name.
- LinkURL - The link clicked by the recipient.
- LinkLabel - If link label is enabled this will display the Real Magnet link label.
Viewing Marketing Automation Information in iMIS
Once integrated with Real Magnet’s marketing automation platform, a few items will now be visible to you in iMIS:
- Additional Activity codes:
- Landing Pages Submitted
- Website Visits
- Goal Reached
- New records created via a Landing Page
Creating Records in iMIS via Real Magnet Landing Pages
When creating a landing page campaign in Marketing Automation, there is an additional option to create records in iMIS. This option is enabled once you create a landing page – there will now be an option to “Integrate this campaign with iMIS,” as you see below:
When records are created in iMIS, Real Magnet will use the email address to define uniqueness. If a record already exists by that email address in iMIS, Real Magnet will ensure that the Custom Member ID is populated with the iMIS ID.
A new record created from a landing page via marketing automation will be created in iMIS as a Prospect.
Frequently Asked Questions
| Question | Answer |
|---|---|
| Why can’t I see my IQA in the list of available lists? | Did you follow the steps to set up the IQA? See Adding iMIS IQAs to the Real Magnet Groups Table. |
| Why am I getting the message “The getCustomDemographicMetadata reply for the query “Query/List Name” does not contain required “ContactId” field. API returned [{“DataType”:”String”,”FieldName”: ”QueryResults”,”Prompt”: ”QueryResults”,”TableName”:””}] metadata”? |
There are two reasons for this error:
|
| Why am I getting a “Missing Field” Error? |
Ensure that the fields are present in the AdHoc Query, IQA, or SQL view – generally, this means an individual removed the field from the iMIS list type. To resolve this:
|
| Why did my query only pull over half of my results? | Did you put in a sort order for that query? Typically, the results for the query are ordered by the iMIS ID; these results are then paged via the integration. If there is a sort applied to a field like an expiration date, for example, the results are no longer ordered in a way that maintains their order via paged results. Remove the sort order of the query and re-run the upload job. |
| Why is there an error message when I attempt to import an IQA or SQL view? | Your query or view must contain the column CONTACTID. |
| Why is there an error message when I attempt to import an IQA? | Your IQA name cannot contain a / –: This will alter the path (location) of the IQA, resulting in iMIS being unable to retrieve the path successfully to export or to update the Real Magnet bridge. Simply remove the slash and re-save the IQA. |
| My adHoc query contains a complex calculation, will the bridge accept it? | No. At the moment, the Real Magnet bridge does not properly handle ad-hoc queries used as calculations if they have sub-select queries in them. The same results can be easily handled through a SQL View. With a little more setup, this could be done with an IQA query as well. |
| Why are there multiple opens or link clicks in my recipient’s activity history? | Real Magnet reports back gross opens and clicks. |
| Why is there no tracking data updating to my iMIS? | Did you select tracking data? Login to Real Magnet and: 1. Select Tools. 2. Select iMIS Management. 3. Select Manage Tracking. 4. Select the Tracking items to sync to iMIS. |
| Why is this individual record missing tracking information? | Ensure that individual is assigned a ContactID. If the individual was uploaded outside of the Real Magnet Scheduler, you must ensure that it also has its ContactID mapped to the Custom Member ID. This is how the iMIS platform identifies that individual in its database. If an individual is missing this information, no tracking information will push back for that recipient to iMIS. |
| Why am I getting the message: “This upload job has one or more groups to which you do not have access.”? | Do you have access to the group? If your account is Enterprise, you'll need to ensure that you have access to the group the Upload Job is connected to. |
| Can I change what Member Type a Record is Created as in iMIS? | Yes. You can make this change by going to General Lookup/Validation > RealMagnet_Settings. You will want to change the table: Prospect_Member_Type, the value in Description must match an existing member Type. |
| Why can’t I see the Sync On Send Option when Sending a Message? | You must at least have Read Only Access for integration upload jobs in order to use this functionality. |
| What happens if the tracking data portion is canceled mid-stream? | Real Magnet logs the failure and re-attempts to send the data through to iMIS. |
| What happens if I am using Internet Explorer? |
Due to Internet Explorer’s security configurations, as part Real Magnet’s compatibility steps, we recommend clients complete the following:
|
|
Server was unable to process request ---> There is an error in XML document (1,337) ---> Instance validation error: 'PasswordExpired' is not a valid value for LogonResultCodes |
The error is related to the Manager password for iMIS - if this value changes it will need to be updated in the Webservice Configuration file. This change can be completed by ATS by reaching out to help@atsol.org. |