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!

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!

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:

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.
  
  

2. Syncing your directory

🛠️ How it works

• Navigate to Settings > Integrations, then locate Direcory Sync and click "Connect."
• You will be taken to a setup portal provided by WorkOS.
• Select your directory provider from the list and walk through the setup instructions for your directory.
• When your directory sync is complete, you will see the linked connection at "Settings" > "Integrations".

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.

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.

We partner with WorkOS to facilitate most of our directory connections. They maintain a receiving SFTP server that can be synced with your organization's HRIS provider/SFTP client.

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.

• Note on attributes: while the WorkOS configuration offers the ability to add additional attributes, Axios HQ does not accept recipient attributes at this time. In the platform, your users can leverage a recipient's name and email address, but cannot create dynamic groups.
  • Despite options like "job_title" being required for the setup, any recipient-pools based on an attribute you would like your HQ users to access in the platform must be created upstream in your provider (or CSV) and imported as groups.
  • You may include N/A for every "job_title" field in your CSV; this attribute is required to facilitate the connection, but it is not necessary to have real data, as we cannot sync the field to HQ.

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

Looking for our Workday SFTP instructions? You can find them here!

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

📚 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.

If a directory member is offboarded via the SCIM group management, is that member automatically disabled / removed from the directory sync (audience)?  

Yes, and this recipient will be removed from all audiences across all series within your organization. However, the users themselves will not be removed from the platform.

• If a member of the directory is also an HQ user, the connections must be viewed separately.
• User access will be revoked when a user is deprovisioned from the SAML app (ie: their account is deleted or marked inactive) but their username will still be visible as a collaborator; the user will simply no longer be able to login.

📚 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 or custom admin role to facilitate the connection. Make sure one of these two accounts officially authenticates any connections to Axios HQ.
  
  • The custom admin role should be configured with the following API privileges:
    • 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:
  • Review the "state" field on the directory member in Azure. If the state is set to "state": "inactive", the member will not be synced to your HQ audience. Learn how to see if your audience members are Inactive, here.
  • You may need to configure attribute mapping in your SCIM app in Azure. Review this tutorial from Microsoft, and consider mapping a known email attribute, such as UPN, to the emails[type eq "work"].value SCIM attribute.

• 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 appearing 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. SFTP is a common connection type for Workday directories, and a set of Workday-specific instructions will be available in the platform.
  • 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).