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 the Authentication Method for your SFTP server:
   • Basic Authentication: Connect using a username and password.
   • SSH Key: Connect using a Secure Shell (SSH) key that you provide, or a key provided by Qualtrics.
8. Use the dropdown to either select an existing connection, or select Add New to set up a new connection. See Adding an SFTP Account for more information about creating a new connection.
9. Click Next.
10. Choose the type of hierarchy:
    • Custom Filter
      • Delta Classification
      • Traditional Classification
    • Attribute Filter
      Qtip: Hover over the information icon next to the hierarchy name to learn about it and its use cases.
11. Click Next.
12. If using a “Traditional Classification” hierarchy type, then you’ll also need to enter a Hierarchy API Token. Otherwise, continue to the next step.
13. Give your hierarchy a name.
    Qtip: You can update an existing hierarchy by making sure the name you enter here matches the existing hierarchy name exactly.
14. Choose your hierarchy settings. The options here depend on your selected hierarchy type from step 10:
    • Delta Classification
      • Upload Organization Hierarchy: Create and activate an organization hierarchy. By default, the activated organization hierarchy is unpublished and will only enable dashboard personalization. When enabled, the following suboptions are also available:
        • Generate groups based on this users file: Create groups based on the organization hierarchy file.
        • Skip non-existent users: Skip users that do not correspond to existing Discover users.
    • 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. This also creates a hidden category model to support additional use cases. The model mirrors the structure and filters of the organization hierarchy. When enabled, the following suboptions are also available:
      • Include records without text: Include records with empty verbatims in your organization hierarchy.
      • Include in incremental dataflows: Include the organization hierarchy in incremental dataflow
        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.
      • Apply to historical data: Apply the organization hierarchy to historical data.
      • Generate groups based on this users file: Create groups based on the organization hierarchy file.
      • Skip non-existent users: Skip users that do not correspond to existing Discover users.
    • Traditional Classification:
      • Upload Organization Hierarchy: Create and activate an organization hierarchy. By default, the activated organization hierarchy is unpublished and will only enable dashboard personalization. When enabled, the following suboption is also available:
        • Generate groups based on this users file: Create groups based on the organization hierarchy file.
      • 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. This also creates a hidden category model to support additional use cases. The model mirrors the structure and filters of the organization hierarchy. When enabled, the following suboptions are also available:
        • Include records without text: Include records with empty verbatims in your organization hierarchy.
        • Include in incremental dataflows: Include the organization hierarchy in incremental dataflow
          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.
        • Generate groups based on this users file: Create groups based on the organization hierarchy file.
    • Attribute Filter
      • Skip non-existent users: Skip users that do not correspond to existing Discover users.
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.