Setting up directory sync

Integrate existing directories into your Axios HQ audience

Axios HQ invites you to bring in your audience in a few different ways: manually add individuals one-by-one, upload a CSV of recipients’ emails and names, or connect your existing directories and have them sync automatically!

⭐ Directory Sync requires an upgrade from the Essential Package. Review our packages here.

Why it matters

  • Setting up a directory sync allows you to connect your current email distribution lists and sync them to Axios HQ.
  • As your email lists change you won’t have to worry about updating your audience to match in Axios HQ. Updates will sync automatically!

Remember: Directory Sync connections bring in your users' recipients, distribution lists, and targeted audience. This connection does not handle user logins.

  • The users at your organization will use the SSO connection log into the platform to plan, write, and send essential communications.
  • The recipients of your series will be synced via the Directory Sync connection; they'll open email series that are engaging, succinct, and intentional in their design.

Table of contents: 

  1. Directory types we support
  2. Syncing your directory
  3. SFTP
  4. FAQ
  5. Common Providers


1. Directory types we support

We partner with WorkOS to facilitate most of our integrations. You can find an introduction to WorkOS and their workflow here.

We support the following directory providers:

Access People HR Hibob SCIM 1.1
BambooHR JumpCloud SCIM 2.0
Breathe HR Microsoft Entra ID/Azure Active Directory SFTP
Cezanne HR Okta (1.1 and 2.0) Workday
CyberArk OneLogin  
Fourth PingFederate  
Google Workspace Rippling  

 

Don't see your provider? Try an SFTP connection! Details below.


Each directory provider has allowances and limitations,
and certain group types within these directories may sync more seamlessly than others. 

Relevant setup options we recommend reviewing include:

  • Nested groups: Nested groups may not sync with Axios HQ. There are often workarounds to bring in this group membership, depending on your directory provider.
  • Dynamic groups: Dynamic groups are those that are gathered with a query, rather than set up individually by a user. Certain directory providers do not support adding dynamic groups to applications within their system.

When you're ready to connect a directory to HQ, you will follow instructions through the portal provided in the platform. Details for this workflow are found below.

If you'd like to review the steps you will be taking, check out the instructions for your specific provider here.

Remember, Directory Sync connections are made to bring recipient lists into HQ (not user logins.) Take a look at the SCIM connections when reviewing the WorkOS docs.


2. Syncing your directory

👉 Navigate to “Settings” > “Integrations”. Then, locate "Directory Sync" and click “Connect”

(You will be taken to a setup portal provided by WorkOS).

💡 Only org Owners and Admins have access to the "Integrations" tab. 

If this view is not available to you, please request that an Owner or Admin in your organization adjust your permissions.

Once in the portal, select your directory provider from the list and walk through the setup instructions for your directory.

At Axios HQ, we currently only use the following attributes:

  • email
  • first and last name
  • member status
  • id
While we work toward making additional fields available within the platform, feel free to limit the attributes your provider sends to us. If you'd like to build distribution groups based on any additional attributes, we recommend creating them upstream in your provider, and importing them into HQ.

🏁 When your directory sync is complete, you will see the linked connection at "Settings" > "Integrations".

  • You will be able to view and modify this connection by selecting the gear icon.
  • You can add synced directory groups to your series by navigating to the "Audience" page and selecting "Manage recipients", then "Manage from directory."


3. SFTP

Does your team use a different directory? An SFTP setup allows your organization to synchronize user and group information by uploading CSV files at a regular, automatic cadence.

WorkOS maintains a receiving SFTP server that can be connected to from your organization's HRIS provider/SFTP client. They are ready to receive your directory setup request, automatically creating and hosting an SFTP folder for your organization's provider to upload files at a regular cadence.

  • Any system that can export the necessary files can be connected via SFTP. This includes directories, Association Management Systems, or other databases.
  • How it works: WorkOS is set up to receive your directory setup request, automatically creating and hosting an SFTP folder for your organization’s data provider to upload files at a regular cadence. Step by step instructions from WorkOS will guide you through an easy setup.

Your team is responsible for writing the script to export the required CSVs for this connection. WorkOS and Axios HQ are configured to accept the output of this code.

As long as you can hit the SFTP host with a public/private key and the username, you can make this connection. WorkOS is looking for a public key -- provided by your team -- and they will provide the username and hosted endpoint.

Having trouble writing the script? Certain vendors can help with data activation and might even provide a free connection!

4. FAQ

📚 Sending

Can I still send from HQ before setting up a directory sync?

Yes! You can still send from HQ before setting up a directory sync. You can manually add recipients by navigating to "Series" > "Audience" and either:

  • Upload a CSV of multiple individuals by clicking on "Manage recipients" and selecting "Import CSV" 
  • Individually add new recipients by clicking on "Add individuals"   

Can I use a CSV and my directory groups?

Yes! Add individuals one-by-one or via CSV at any time. If a CSV is uploaded or deleted, contacts added via Directory Sync will not be affected. If a recipient is on a CSV and synced via directory sync with the same email address, they will not receive an edition twice.

📚 Troubleshooting

My recipients aren't syncing / I see my recipient is listed as "Inactive"

Review your directory connection by navigating to Settings > Integrations > Connected Apps. Find your directory connection and click the gear icon.
You will be taken to a setup screen that will provide overview information for your integration. This is a direct peek into the Azure connection you've set up. If you can see individuals listed as "inactive" in your directory configuration, they will not be synced to your HQ audience.
Members can be listed as "inactive" in the directory when certain fields in the member's information (like "state" or "status") are set to something such as "disabled," "suspended," or simply "inactive." These information fields are alongside keys like "name" and "email."
Reach out to your IT team, so they can edit your members' configuration.

📚 Access

Who can access my organization's synced directory?

Only Owners, Admins, and Members with granted permission can access your synced directory.

Can I restrict access to certain synced directory groups?

Some providers may allow you to select specific directory groups in the setup options. Others will sync all available groups.

Within Axios HQ, users either have access to the synced directory or they do not; at the moment, our platform does not support restricting user access to specific directory groups.

Will synced members (recipients) gain access to the platform?

No. Synced audience members (recipients) will not gain access to the platform. Access is only granted by inviting users to your organization and through our SSO integration.

📚 Sync

How often will syncs be performed?

  • BambooHR, Breathe HR, Cezanne HR, Fourth, Google Workspace, HiBob, and  Workday directories poll every 30 minutes starting from the time of the initial sync.
  • Okta SCIM 2.0 directories sync events in real time.
  • By default, Entra ID SCIM 2.0 directories sync events on a scheduled time interval, typically every 40 minutes. There's also an option for on-demand provisioning which syncs events in real time.
  • SFTP syncs will happen at a cadence set by your team! 

We have more than one directory, how can I sync them both?

Reach out to us at help@axioshq.com to set up an additional directory. Each organization is entitled to two directories without charge, and can add more connections for an additional fee.

📚 Security

Can we review WorkOS's Privacy Policy?

Yes, check out WorkOS's Privacy Policy and Security FAQs here.

 


5. Common Providers

Below is a list of common Directory providers and some additional recommendations and troubleshooting tips.

  • Google Workspace
    • Google's setup requires a Super Admin to facilitate the connection. Make sure a Super Admin account officially authenticates any connections to Axios HQ.
    • You also have the option of setting up a custom admin role with the following API privileges for this connection:
      • Users > Read
      • Groups > Read
    • If your team has only synced select Google groups, you can add more to your setup by navigating to  Settings > Integrations > Connected Apps, and selecting the gear next to your connection. Under the "Group sync" heading, edit the groups you'd like to bring into HQ!
  • Microsoft Entra ID (Azure Active Directory)
    • Microsoft directories can be synced via Enterprise Application or App Registration. Check out our comparison page if your team is using Entra ID/Azure AD to see which setup would be best for you.
      • Our self-serve portal available in the HQ platform only provides the option for the Enterprise Application. If your directory configuration is incompatible and you would prefer an App Registration, reach out to help@axioshq.com.
    • We are not able to sync with Azure on-premises directories at this time.
    • Any groups synced to an Enterprise Application in Azure Active Directory must be security groups. For this reason, you can sync a Dynamic Distribution Group, but cannot sync a Dynamic Distribution List.
    • If your Azure Active Directory setup is not pulling in email addresses:
    • WorkOS, by default, syncs a number of attributes to HQ. The only attributes we currently sync from Azure to ensure functionality are:

      userPrincipalName Switch([IsSoftDeleted], , "False", "True", "True", "False")
      mail displayName
      surname givenName
      objectId Join(" ", [givenName], [surname])
    • Okta
      • Organizations that plan to sync Okta for both Directory Sync and SSO connections should create two separate applications, one for each connection. This will avoid users provisioned for SSO from being mistakenly pulled into the Directory Sync.
      • If you are encountering issues with users not appearing in the sync:
        • For Okta applications that have both SCIM and SAML, users that were assigned to the app before provisioning was added will need to be provisioned before they can be synced.
      • Users must be assigned to the directory sync application you are configuring. Some organizations may want to limit this, to avoid Axios HQ from appeared as an application that can be clicked on the users' dashboards. However, this step is required for the directory sync. We suggest completing this step and then hiding the application tile from the users' portals, if this is a concern.
    • Workday

      • Workday offers two connection types:

        1. One uses a single Group and User report to connect your directory for a quick and easy sync! Each user (ie: recipient) is expected to be available in only one group. Learn more here.
        2. The other uses an SFTP connection, which will allow your recipients to exist in multiple groups within your directory. 
        • You can can create an XSLT transformation to make the custom reports for this connection in CSV format.
        • An XSLT transformation will also enable you to convert multiple data sources (Location, Department, etc.) into one CSV file (this is especially helpful for the required user_groups.csv file).