Organization Hierarchy Inbound Connector

About the Organization Hierarchy Inbound Connector

Organization hierarchies allow you to upload your organization structure to XM Discover to improve data analytics, user personalization, and data access control. You can use the organization hierarchy inbound connector to upload and update organization hierarchies.

Preparing an Organization Hierarchy File

Before you can set up an organization hierarchy inbound job, you must make sure your organization hierarchy data is in the proper format and contains your organization structure.

Organization hierarchies can be uploaded using a CSV or Excel (XLS or XLSX) file.

See the Best Practices for Organization Hierarchies for examples and formatting guidelines for each file type.

Example: Below is an Excel file showing an example organization structure for a hotel company.

Setting Up an Organization Hierarchy Inbound Job

Follow the steps below to set up an organization hierarchy inbound job. This setup requires you to generate a Hierarchy API token in Studio, which is recommended before completing the steps below.

1. In the Jobs tab, click New Job.
   
2. Choose Organization Hierarchy.
   
3. Give your job a name so you can identify it.
   
4. Choose the project to load data into.
5. Give your job a description so you know its purpose.
6. Click Next.
7. Choose an SFTP account to use, or select Add New to add a new one.
   
8. If adding a new account, enter the following information for your SFTP account:
   • Connection Name: Give the connection a name so you can recognize it later.
   • SFTP Username: Enter the username to connect to your SFTP server.
   • SFTP Password: Enter the password to connect to your SFTP server.
   • SFTP Host: Enter your SFTP server host URL.
   • SFTP Port: Enter your SFTP Port. Usually this is 22.
   • Send Expiration Notifications: If you’d like your SFTP credentials to expire after a certain amount of time, select this option.
   • Days Prior Expiration: If enabling expiration notifications, enter how many days you’d like to be notified before the expiration. You may enter a value between 1 to 100 days.
   • Expiration Date: Set the date when the credentials will expire. Click on the box to open a calendar to pick the date.
9. Click Next.
10. Enter your Hierarchy API Token.
    
11. Click Next.
12. Give your organization hierarchy a name.
    
13. Choose if you’d like to publish your organization hierarchy or not:
    • Upload Organization Hierarchy: Create and activate an organization hierarchy. By default, the activated organization hierarchy is unpublished and will only enable dashboard personalization.
    • Upload Organization Hierarchy and Publish: Create, activate, and publish an organization hierarchy. Publishing an organization hierarchy enables you to group data by its levels. This is a prerequisite for peer and parent reporting and target and variance reporting.
      Qtip: Publishing an organization hierarchy creates a hidden corresponding category model to support additional use cases. The created category model will mirror the structure and filters of the organization hierarchy and behave like a model where applicable.
14. Select additional hierarchy options depending on your preferences:
    • Generate groups based on this users file: Create groups based on the organization hierarchy file.
    • Include records without text: Include records with empty verbatims in your organization hierarchy. This option is only available if you are publishing your organization hierarchy.
    • Include in incremental dataflows: Include the organization hierarchy in incremental dataflow runs. This option is only available if you are publishing your organization hierarchy.
      Qtip: If you expect that publishing an organization hierarchy will conflict with other dataflows, we recommend deselecting this option. The model that gets created and subsequently classified will not block other dataflows if this option is disabled.
15. Click Next.
16. Choose the type of file you want to upload:
    
    • Delimiter-separated “flat” Files
    • Excel Files (XLS, XLSX)
17. For delimiter-separated flat files, there are additional settings for you to choose:
    
    • File encoding: Choose the file’s encoding system (UTF-8, ASCII, etc)
    • Delimiter character: Enter the character used to delimit data entries. By default, this is a comma for CSV files.
    • Enclosure character: Enter the character that encloses data entry. Leave this field blank if “No enclosure” is selected.
    • No enclosure: Enable this option if your file does not contain enclosure characters.
18. Click Browse and choose the folder path on your SFTP server that contains the file you’d like to upload.
    Qtip: When choosing a folder path, you can click on a folder icon to expand that folder. Click on the folder name to select that folder, and then click Ok when done.
19. Enter the filename regular expression that matches the files you want to upload.
20. If your files are compressed, enable Unzip file(s) and enter the Zipped Filename regular expression that matches the files that should be decompressed.
    
21. If your files are decrypted, enable Decrypt file(s) and enter the following:
    • Encrypted Filename regular expression: Enter the filename regular expression for files that should be decrypted.
    • PGP/GPG key: Enter the PGP/GPG key used for encryption.
    • Passphrase: Enter the passphrase for decryption.
22. If your files are both compressed and encrypted, you must choose which should happen first:
    • Unzip then Decrypt: Files are decompressed and then decrypted.
    • Decrypt then Unzip: Files are decrypted and then decompressed.
23. You must provide a sample file, which can be either saved on your computer or on your SFTP server:
    
    • Select Download Sample from File Storage if the sample file is saved on your SFTP server.
    • Select Upload sample from my computer if the sample is saved to your computer.
      Qtip: If needed, you can download a template file by clicking the here link displayed in the job setup.
24. By default, your sample file is not used to generate the organization hierarchy. If you’d like your sample file to be used for the first job run, then enable Use uploaded sample file for initial job run.
25. Click the Select File button and choose the sample file on your computer or on your SFTP server.
26. A preview of the file will appear. If you see an error message or raw file contents instead of the preview, there may be a problem with the data format options you selected. See Sample File Errors for help troubleshooting your file.
27. Click Next.
28. Begin mapping fields from your sample file to organization hierarchy fields in XM Discover. Click the box in the Mapping column to choose an XM Discover organization hierarchy field to map to your imported field. The possible organization hierarchy fields include:
    
    • Level 1 to Level 10: Define the structure of your hierarchy. The maximum number of hierarchy levels is 10.
    • Users: Map the users to your hierarchy.
    • Filters: Define the filters for your hierarchy.
    • Enrichments: Create enrichment parameters for your hierarchy. The maximum number of enrichments is 6.
29. If needed, you can transform incoming data by clicking the gear icon in the Transformations column.
30. You can add additional fields by clicking the plus sign ( + ) or remove fields by clicking the minus sign ( – ) nex to the field.
31. Click Next when you’re finished mapping fields.
32. Choose your notification settings.
    
33. Click Next.
34. Choose Schedule Incremental Runs if you’d like your job to run periodically on a schedule, or Set Up One-Time Pull if you’d like the job to run just once. See Job Scheduling for more information.
    
35. Choose a retention period for processed files. Files are deleted after the set period.
36. Click Next.
37. Review your setup. If you need to change a specific setting, click the Edit button to be brought to that step in the connector setup.
    
38. Click Finish to save the job.