EBS: Everbridge Contact Sync Overview - Choosing Between File Upload (SFTP) and Individual Contact Sync (API) for Contact Uploads

Table of Contents

Everbridge Contact Sync Overview

One of the first things to consider when using the Everbridge platform is how to get your information into the system. This document focuses specifically on getting your contact data in. In this case Contact data is all data associated with delivering messages to people.

In general, we recommend getting your contact data into the Everbridge cloud platform using a simple CSV Replace file.

What is a CSV Replace file and why is this recommended?

A CSV file in the most basic terms is a simple comma delimited file (you can even read it in Excel). You just need to export your people from your existing HR system (or any system of record) into the Everbridge format and upload it.

Common questions answered in this document:

  • How do I handle deletes?
  • I have 50,000 records;do you really expect me to load them all into your system ever day/week?
  • I don’t want to do this manually; can this be automated?

Where do I start?

To migrate your contact data into Everbridge we recommend you start with your IT or HR Department. They usually have some “System of Record” that has a list of all people you will need to load into Everbridge. When you find the IT or HR person ask them, “If something goes with your system who do you contact?” Chances are that is the person who will be able to help you extract the data or at least point you in the right direction. If you find the right person, your next steps will be to work with your Everbridge implementer to map out how your Everbridge system should be set up based on the information available.

I want to update my contacts in real time.

After taking a deeper look into real time contact sync, most customers opt to use SFTP file upload.

Introduction

Purpose

The one activity common to ALL implementations of  the Everbridge platform is the use of contact data. There is a lot of  confusion out there about the best way to get your contact information into Everbridge. Unfortunately, there is no magic data wand that will perfectly sync your data with Everbridge.

We all know Everbridge has the world’s greatest delivery engine (just ask our sales and marketing teams), but to use it, you first need to get your information into the system. It is also advisable to keep it updated; but one step at a time.

How do you get your information into Everbridge?

Luckily for you,the engineers at Everbridge have given this a lot of thought and have come up with a few different ways. This document explains your options and will help you decide the correct option for you and all your data needs.

When you are done reading this document, you should have a much better idea of  how to keep your contacts.... wait for it... *N Sync.

Overview

The most common misconception in the world of  Everbridge contact syncing is that you have two main options: SFTP or API. This is NOT how you want to think about it. The two main ways to sync your contacts are really:

  1. File Upload
  2. Individual Contact Sync

We are going to say this again because it is the most common mistake made when talking about getting contact information into Everbridge. Your two main options are File Upload or Individual Contact Sync.

Sometimes we get asked the question: “Can Everbridge extract(pull) data from a customer system?” The quick answer is no. The long answer is that the Everbridge infrastructure is just not designed to handle pulling data into its environment. To create a mechanism that will extract data from a third party and pull it into Everbridge would require a whole new framework and a working knowledge of  the customer system.

Other Considerations

  • In general, Everbridge should not be used as a SOR (System of Record).
  • Try to use a version of the KISS principle (Keep It Simple and Stupid).

Methodology Decision Tree

Using the Decision Tree

You can use a decision tree to decide what methodology to use to get your information into Everbridge. By following this tree, it will help you figure out the best way to get your information into Everbridge.

User-added image

File Upload Versus Individual Contact Sync

The first question to ask: Do you want to sync contacts using “File Upload”or “Individual Contact Sync”? What is the difference?

Like everything else, the two different methods have pros and cons. When looking at these two options, the File Upload is by far the simpler solution. It is recommended that whenever possible you use the File Upload. There might be rare cases where a true real-time contact sync is needed, but think long and hard before you choose this option.

But I want my contact data to be up-to-date at all times:

When someone says they want to do individual contact sync, here is what we usually say:

  • If you have an international organization or a system that allows a contact to update their own data, then the data may change constantly.
  • If you follow Everbridge best practices and use multiple modalities, the chances that BOTH a catastrophic event that impacts specific contacts AND none of  their contact data is current are very low.
  • You could even do a file upload twice a day, but statistically speaking, it is probably not necessary.

File Upload Versus Individual Contact Sync Comparison

The "PROs" are in green.
Area SFTP - File Upload API - Individual Contact Sync
Cost
  • Developing a file upload is relatively quick and straightforward.
  • SFTP is included in your purchase.
  • This option can be VERY costly to develop and maintain. Our estimates are around 10 to 100 times more expensive than file upload.
  • API is an extra expense.
Data Extraction Getting data out of most SOR systems into a CSV format is relatively straightforward. It is most likely something your Admins have done before and know how to do. To get data out of the SOR system,either 1) your developers would need to figure out how to do it, or 2) It might be possible to have your SOR Admins do it in a text format, but at that point you might as well upload the file.
Documentation Every aspect of the file upload is well-documented. References to everything you need to know for file uploads can be found in Knowledge Base Article 000049845 - Troubleshooting Guide: Contacts and Contact Uploads. API documentation is available but it is not nearly as complete as for File Upload. There will also be activities you need to do that are not documented like how to resolve all the references.
Everbridge Support The Everbridge Technical Support team is well versed in how the File Upload works and can help you track down most problems you encounter. Support is not as familiar with API and is unable to help debug your code.
Maintenance It is easy to add/remove data fields. It can require as little as changing one line that does the data extract. If  you want to add a new field, you would need to find a developer resource, they would need to become familiar with the existing implementation, develop changes, and test to make sure they did not break anything.
Reliability You are only making one call outside your infrastructure. If that call fails, you can always do a manual upload until you resolve the problem. Requires numerous API calls; one for each operation (Get, Put, Post, Delete). Each API call has a chance to fail!
Resources Just your SOR admin and some help from someone in IT who knows how to schedule a job. Requires a software engineer with the following skill sets to build:
  • SOR extract knowledge
  • CSV formatting
  • RESTful API
  • JSON
Time to Live To go live with this option, you just need to figure out how to extract the data. You could then upload it manually and start using Everbridge. Full automation is simple once you have your upload file. This can take a while! You usually cannot go live until all the development is complete, fully tested, and moved to production.
Encryption Options For SFTP, Everbridge only supports the use of our key. If you cannot use our key with your SFTP process, then you cannot use SFTP. You can use your own encryption key.
Failure Recovery Depends on the File Upload type. If Replace is used, it is easy. Just upload the file or wait until tomorrow. If UPDATE is used, you will need to reprocess the files that failed. Very hard. How do you keep track of  all failures and what data failed to update? Usually a full re-sync capability will be required.
Error Handling This is easy with a File Upload. You can go into the UI and see what the errors are. You also have the option to inspect the file in Excel. You need a developer to look at any issues here. Everything is done with JSON objects and IDs. You need to hope your developer has good error-handling skills.
Data Accuracy Data can be as old as your last file upload. To get more real-time data,you can consider using “Last Known Location”. Data can be kept up-to-date in real time.
Flexibility There are some activities you cannot do with a single file upload,such as maintain a “Manually Managed” group. Complete flexibility. With this solution, you can do anything anyway you want. There are also some fields you can update with API that you cannot update via the File Upload such as:
  • Subscriptions
  • Quiet Times

Individual Contact Sync

If you have chosen to go with individual contact sync, there is a good chance your situation is unique and Everbridge suggests you reach out to Professional Services for assistance with your special requirements.

File Upload

File Upload First Consideration

When you sync contacts with Everbridge using file upload, there are three actions you need to do:

  1. Create contacts
  2. Update contacts
  3. Delete contacts

Replace File vs Update/Delete

You can accomplish these in two different ways:

Replace. This method requires one file:

  • A Replace file. Super easy, what you send in is what you will get. If the replace file works for you, then go for it!

Update/Delete. This second method requires two files:

  • An Add/Update file. This creates any new contacts and updates existing contacts.
  • A Delete file. This removes contacts.

Why do we recommend a Replace file?

Have you ever tried to figure out who was removed from a system? It is not easy. You need to compare a version of  all contacts from the last upload file to the new upload file. Then you figure out everyone who is missing, build the delete file,and upload it. What happens if you miss someone, do they stay in Everbridge until you do an audit?

If you can create a Replace file, your life is much easier. You dump out your HR system data as a Replace file and upload it. Let Everbridge do all the work. If  a contact is NOT in your replace file, then he or she is automatically removed.

What are the situations where you can and cannot use a Replace file?

The main reason you might not be able to use a Replace file is if you have multiple sources for contacts with the same record type. In this situation, we suggest you discuss your options with your implementation specialist.

For more information on Replace and Update, see Knowledge Base Articles:

Getting File Upload Working

First, let us congratulate you on choosing the File Upload!

Replace File

Get ready for these two big steps:

  1. Extract your data into Everbridge format.
  2. Transfer the file to Everbridge.

Update and Delete Files

For this part:

  1. You will need to extract your add and change records into one file and all your deletes into another file. This can be a little tricky. You might want to check with your SOR Admin on how to do this.
  2. Transfer the files to Everbridge.

All Options

From your SOR, you will need to extract your contact data to conform with the Everbridge upload file format.

More information about the data format can be found under Contacts > Uploads > Download Template:

User-added image

For detailed information on the file format for contact uploads see the following Knowledge Base Articles:

There is also a lot more information available in the Everbridge online help sections that provides details of each column in the CSV file.

File Transfer - Testing

At this point you should have your file(s) ready for upload to Everbridge. Something to keep in mind is that there are three ways to upload a file. All three ways work exactly the same.

  1. UI (User Interface) – You can log into the UI and upload the file manually.
  2. SFTP – Everbridge has the ability to accept a file via Secure FTP.
  3. API – There are calls under /uploads that allow you to send a file via API.

Just to reiterate, all three of  these methods work the same way.

Now that you have your file(s),you can easily test them using the UI. Use the UI to perform the transfer. This will allow you to find any errors with the upload file before you try to automate the process. This is like learning to walk before you run.

File Transfer - Automation

If you made it this far, you are only one step away from using the Everbridge platform. There is one more decision to be made.

The one last question is, should I use SFTP or API for the file upload?

Things to consider:

  • SFTP is included in your purchase. The API might be an extra expense.
  • For SFTP, Everbridge only supports the use of our key. If you cannot use our key with your SFTP process, then you cannot use SFTP.

When it comes to support, we have documentation on both SFTP and API. Log into the Everbridge Support Center to find all kinds of documentation on both.

File Upload Common Questions

These common questions only apply to the file upload. Watch Formatting a File for Upload on YouTube for more information on these commonly asked questions. For the Individual Contact Sync you will need to work with Professional Services.

What is the required data for any contact?

  • First Name
  • Last Name
  • External ID
  • Record Type

Do I need all the headers in the file upload template?

No, you do not need all the headers. The only required headers are listed above. The order and number of headers does not matter. Everbridge will only update the fields for headers included in your upload file.

Note: As a best practice, only include the headers are you using. For example, if you do not include a column for Email 2, then the Email 2 field will not be updated.

How do I tell if I have the file format correct?

If you have a test organization, just upload the file and look at the upload file results in the UI. It gives you details for all errors.

User-added image

To see more details click on the binoculars to the left the upload you want to view.

User-added image

Contact Uploads Help

  1. From the manager portal click the ? in the upper right corner to display the HELP & SUPPORT drop-down menu.
  2. Select Online Help.
  3. Search for Contact Uploads in the search bar and select the appropriate option, or
  4. In the Table of Contents to the left, click on Organization Administrator > Who Are Contacts.
User-added image

Resources

  • A valuable resource for everything contact and contact upload related is Knowledge Base Article 000049845 - Troubleshooting Guide: Contacts and Contact Uploads which has pointers to videos, articles and training on contacts and contact uploads. This is a great starting point for learning, designing, and troubleshooting questions and issues related to contacts and contact uploads.
  • Everbridge Support Center - Everbridge customers can access the Support Center by logging into the Manager Portal (manager.everbridge.net or manager .everbridge.eu) and choosing Help & Support from the far upper-right of the page, then the Everbridge Support Center link. You can peruse the entire knowledge base from the support center to find all available documentation on contact and contact upload related information.
  • Online Help in the Manager Portal - Everbridge customers can access the Online Help by logging into the Manager Portal (manager.everbridge.net or manager.everbridge.eu) and choosing Help & Support from the far upper-right of the page, then the Online Help link.
  • Everbridge University YouTube. Here you can find short tutorials on contacts and contact uploads as well as many other Everbridge-related topics.
Was this article helpful?
0 out of 0 found this helpful

Comments

0 comments

Article is closed for comments.