Manage Domains

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Customer Managed Applies to customer-managed instances of Alation

Create a New Domain

You must be a Catalog Admin or Server Admin to create a new domain.

To create a new domain:

  1. Go to Apps > Domains.

  2. Click + Create Domain to create a new domain.

  3. Provide the Title of the new domain.

    Note

    Avoid clicking Create Subdomain as it will create a new nested domain instead of saving the current title.

  4. Click the Edit button to provide the description of the domain.

Create a New Subdomain

You must be a Catalog Admin or Server Admin to create a new subdomain.

To create a new subdomain:

  1. Go to the parent domain’s catalog page.

  2. Click the Create Subdomain button in the top right corner.

  3. Provide the Title of the new subdomain. Click the Edit button to provide the description of the subdomain.

Add Objects to a Domain

Alation users who author or own objects can add them to domains. For example, query authors can add their queries, article authors can add their articles, and object stewards can add their objects. Catalog Admins and Server Admins can also add objects to domains.

Objects are included into domains and subdomains according to the following rules:

  1. Domains/subdomains can have any number of objects mapped under them.

  2. An object can be added to any number domain/subdomains.

  3. An object that has parent objects can be added to a domain independently from its parent objects.

  4. When a parent object is added to a domain its child objects can be recursively added to this domain. A child object can be excluded from a domain if necessary.

To add a supported data object to a domain or subdomain:

  1. Go to the object’s catalog page.

  2. Check to see if the object is already a member of the desired domain. Is the specific domain already listed under the Domains section? If it isn’t, it may be indirectly referenced with a subdomain. Hover over each listed domain and observe the individual domain breadcrumbs. Is the domain listed as a parent? If so, the object is already a member of that domain and there is no need to add it again. If not, continue on with the subsequent steps.

  3. On the object page, click the + icon in the Domains section.

    ../../_images/ManageDomains_06.png

  4. A list of domains and subdomains appears. Select any domain/subdomain to add the object to the applicable domain/subdomain.

    Note

    The listing does not specify any difference between the domains and subdomains.

  5. Choose whether to add this object and all its child objects or add a single object only (shallow add), without adding the child objects.

    • Choose Add this object and all of its current and future children to this domain to add the parent and the child objects to the domain. If any new child object is added to this parent later will also be added to the domain.

      Note

      Objects with many child objects will take some time for the change to be reflected on all child object pages and in search.

    • Choose Add only this object to the domain to add only the selected parent object.

Add Users to a Domain (Public Preview)

From version 2024.1.1

Important

To participate in the Federated Catalog public preview, you must have Beta language contained in your contract or have a Beta addendum signed.

To enable Federated Catalog, use the Enable Federated Catalog Features toggle on the Admin Settings Feature Configuration page.

If the Federated Catalog feature is enabled, users can filter the catalog search and navigation based on their preferred domains.

You can add users and groups to a domain, and that domain will appear as a suggested domain filter for those users, as long as they haven’t yet changed their filter. Once a user changes their domain filter, adding them to a domain has no effect.

You must be a Catalog Admin or Server Admin to add users to a domain.

To add users to a domain:

  1. Go to Apps > Domains.

  2. Navigate to the domain you want to assign users to.

  3. In the Domain Users section on the right, click the plus (+) button.

  4. Select the users or groups you want to add. The user or group will appear in the list under Domain Users. This domain will be added to their domain filter, as long as they haven’t yet changed their filter.

You can also use the My Domains API to add users to a domain.

Delete a Domain

Deleting a domain removes the domain and its subdomains and unassigns all objects from them. If a domain has multiple levels of subdomains and many objects mapped within subdomains, Alation recommends deleting the inner levels of subdomains first, working your way out to the targeted domain. Pausing between domains is useful to ensure time for search indexing updates. Failure to do this may result in other low priority search updates taking even longer to be reflected in search results.

You must be a Catalog Admin or Server Admin to delete a domain.

To delete a domain, go to the domain’s catalog page, then click Delete in the top right corner.

Note

After deleting, it will take some time to reflect the change in the object catalog pages.

Customize the Domains Page

Server Admins and Catalog Admins can customize the domains page to facilitate better curation. Go to Settings > Catalog Admin > Customize Catalog > Custom Templates > Domain.

../../_images/ManageDomains_11.png

To customize, refer to Customize Your Data Catalog.

Schedule Domain Membership Updates

When an object is added to a domain, that object’s children can be automatically added to the domain by default. However, the children are not added to the domain immediately. A dedicated server job, known as the domain materialization job (domains_materialize_domain), must be run to update domain membership. The job can be enabled and scheduled using alation_conf as described below.

Note

Alation Cloud Service customers can request server configuration changes through Alation Support.

You must be a Server Admin to enable and schedule the domain materialization job.

Enable the Materialization Job

To enable the domain materialization job:

  1. Use SSH to connect to the Alation server.

  2. Enter the Alation shell using the following command:

    sudo /etc/init.d/alation shell

  3. Enable the materialization job:

    alation_conf alation.domains.materialize_all_domains_job.enable -s True

  4. Restart celery:

    alation_supervisor restart celery:*

Schedule the Materialization Job

The materialization job is scheduled to run weekly by default, at 4 AM every Sunday.

To adjust the default schedule, a Server Admin can use these dedicated alation_conf parameters:

  • alation.domains.materialize_all_domains_job.schedule.day

  • alation.domains.materialize_all_domains_job.schedule.hour

  • alation.domains.materialize_all_domains_job.schedule.minute

The parameters values use cron syntax. For help on setting alation_conf parameters, see Using alation_conf.

After you’ve changed any of the values, restart the celery-beat component:

alation_supervisor restart celery:celery-beat

Duration of the Materialization Job

The domains_materialize_domain job can take a long time. Its duration depends on how many objects belong to the domains. For example, materializing five million domain member objects is estimated to take about 24 hours on an m4.2xlarge host.

If the materialization job is still running when the next job is scheduled to begin, the next job will be skipped.

A Server Admin with access to the Alation server can find the details of the materialization job execution in the celery-domains_error.log file.