System Overview

Unily is a modern employee experience platform that enables enterprises to create, manage, and distribute content across the organization. From a Moveworks enterprise search perspective, Unily serves as a consolidated source from which Moveworks ingests both article content and file attachments.

Authentication

Moveworks uses OAuth 2.0 Client Credentials to authenticate directly with your Unily tenant.

Permissions Enforcement

Moveworks honours all user access controls, ensuring that individuals only see search results for content they are permitted to view.

Content Types

The Unily connector for Moveworks supports the following content types:

Supported content types : Moveworks can ingest content from the following Unily entities: Site Pages, News, Events, Insights, Articles, FAQs, Locations, Apps, Knowledge Articles, Files, Custom Documents.

Supported Formats: For file attachments and documents, Moveworks supports: PDF, DOC, DOCX, PPT, PPTX, HTML, Widgets - Rich Text Editor Base, Content Card, Sortable Accordion, Links Rollup, App List Rollup, Page Title Banner and Content Highlight with Media.

Access Requirements

Moveworks connects to your Unily instance using OAuth 2.0 (Client Credentials Grant). To enable this, please contact your Unily Admin or the Unily Support Team to provision an API client and provide the following details to Moveworks:

• Unily Instance API URL
  • e.g., https://orgname-api.unily.com
• Client ID
• Client Secret
• Required OAuth scopes (listed in the table below)

These credentials and scopes allow Moveworks to securely obtain access tokens, query Unily content for enterprise search and respect the permissions enforced by Unily’s APIs.

Required Scopes:

Testing your Unily API credentials (Optional)

It’s a good practice to verify that your Unily API credentials have access to all the endpoints required for Moveworks ingestion. You can validate this using Postman or any tool that supports cURL commands.

• Auth

  1
  curl --location 'https://{unily_base_url}/connect/token' \
  2
  --header 'Content-Type: application/x-www-form-urlencoded' \
  3
  --data-urlencode 'grant_type=client_credentials' \
  4
  --data-urlencode 'client_id={client_id}' \
  5
  --data-urlencode 'client_secret={client_secret}'
  Use the returned access_token as a Bearer token for all subsequent API requests.
• Content

  1
  curl --location 'https://{unily_base_url}/api/v1/search' \
  2
  --header 'Content-Type: application/json' \
  3
  --header 'Authorization: Bearer {access_token}' \
  4
  --data '{
  5
    "query": "query ($queryText: String!, $take: Int, $skip: Int) { content { byQueryText(queryText: $queryText, take: $take, skip: $skip) { totalRows data { id parentId published lastModifiedDate createDate updateDate nodeTypeAlias } } } }",
  6
    "variables": {
  7
      "queryText": "+(nodeTypeAlias:SitePageModern nodeTypeAlias:Insight nodeTypeAlias:News nodeTypeAlias:ufsFAQ nodeTypeAlias:Event nodeTypeAlias:Video nodeTypeAlias:ufsLocation nodeTypeAlias:ufsNewsAdvocacy nodeTypeAlias:ufsInsightAdvocacy nodeTypeAlias:ufsEventAdvocacy nodeTypeAlias:ufsVideoAdvocacy nodeTypeAlias:App nodeTypeAlias:ufsKnowledgeArticle nodeTypeAlias:unilyDocument nodeTypeAlias:customDocument nodeTypeAlias:ContentGridVariant) +isPublished:True +isTrashed:False",
  8
      "take": 3,
  9
      "skip": 0
  10
    }
  11
  }'
  • From the /api/v1/search response, pick the first item’s id.
  • Call the content detail API using that ID.

    1
    curl --location 'https://{unily_base_url}/api/v1/content/{ID}' \
    2
    --header 'Authorization: Bearer {access_token}'
• Permissions

  1
  curl --location 'https://{unily_base_url}/api/v1/read-access-assignments?pageSize=3' \
  2
  --header 'Authorization: Bearer {access_token}'
  This endpoint returning a 200 response with data validates that we can fetch the permissions and access-assignment data required for enforcement.
• Groups

  1
  curl --location 'https://{unily_base_url}/api/v1/groups?pageSize=3' \
  2
  --header 'Authorization: Bearer {access_token}'
• Users

  1
  curl --location 'https://{unily_base_url}/api/v1/users?pageSize=3' \
  2
  --header 'Authorization: Bearer {access_token}'

Setup in Moveworks

Connector Creation

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Connectors > Built-in Connectors
3. Click Create New
4. Search and Select Unily (Next Gen)
5. Click on Next: Add Creds
6. Input the following details
   1. Connector Name : Name this connector for your future reference. Once set, this name cannot be changed.
   2. Authentication Type: Select OAuth2 Client Credentials Grant option
   3. Client ID: Enter the Client ID you obtained from your Unily admin.
   4. Client Secret: Enter the Client Secret you obtained from your Unily admin.
   5. Base URL: Enter the URL for your Unily API instance.
7. Click Save.

This connector will now be used to configure content ingestion from Unily. Refer to the steps mentioned below.

Configuring Unily for Enterprise Search

Initialising setup

1. Log in to your org’s MyMoveworks portal
2. Navigate to Moveworks Setup > Search > Configure Search > Max Capacity
3. Click on Create New or Get Started
4. Select Unily from the dropdown list and click on Get Started
5. You will be redirected to the Unily ingestion overview page. In the overview page, you will find few info blocks and few configuration blocks.
   1. System Overview: This presents an overview of Unily support from Moveworks
   2. Ingestion Summary: This provides information on the count of records that has been ingested and serving. The values will appear after the first successful ingestion run.
   3. Connector Selection: In this configuration block, you are required to select the required connector to enable Moveworks to connect and fetch data
   4. Content Selection: In this configuration block, you are required to define the content that should be ingested within Moveworks

Connector selection and validation

1. Once you click on Select Connector, a connector setup screen will appear as follows

2. Select the connector (from the dropdown) that you have created in the Connector Creation step.

   Please note: Only the Unily (Next Gen) connectors will appear in this list.

3. Once the connector is selected, you need to click on Start Validation to validate the connector credentials and required scope.

   Connector Validation

   This is a mandatory step in order to save the configuration and move to the next step.

   Moveworks validates the selected connector to check:

   • Auth: Moveworks validates if the connector has right credentials to authenticate
   • Content: Moveworks validates if connector has right scopes to fetch content
   • Permissions: Moveworks validates if connector has right scopes to fetch user permissions
   • Users: Moveworks validates if connector has right scopes to fetch user data
   • Groups: Moveworks validates if connector has right scopes to fetch user groups data

4. If the connector is validated successfully, you will see a green info banner as follows

   1. If there are any credentials or scope issues, you will receive an error message. Click on View Details to identify the issue. Refer to this step-by-troubleshoot guide (link to be added) to rectify any validation errors.

5. Once the connector is validated successfully, you will be able to Save the configuration.

6. Input the unique configuration name and Save.

7. Once the configuration is saved, you can view the unique configuration name at the top of the screen. You can also click the pencil 🖊️ icon to edit the configuration name.

8. Additionally, you will start seeing an entry of your configuration in the Enterprise Search home page. You can click on your configuration to go to edit/ complete the configuration

Content Selection

Once the connector selection step is complete and the configuration is saved, you will now be required to define the scope of content that will be ingested in Moveworks.

1. Once you click on Select Content, a content selection screen will appear as follows.
2. In this screen, you are required to define the Sites from which Moveworks will ingest content and apply filters (optionally) to filter down the content further.
3. Site Selection: This is a mandatory configuration. This configuration defines which sites Moveworks will crawl and ingest content from. As an admin, you get three option

   1. All sites (Recommended): Moveworks will ingest content from all applicable sites

      When to choose this option? Choose this option if you want employees to search across all content across all sites. Moveworks will automatically respect all existing user permissions.

   2. Only selected sites: Moveworks will only ingest content from specified sites.

      When to choose this option?

      Choose this option if only certain sites are relevant. You’ll just need to enter the Site IDs during setup.

      How to configure? Select this option and enter comma separated Site IDs.

   3. All except selected sites: Moveworks will ingest content all except specified sites.

      When to choose this option?

      Choose this option if certain sites are not relevant for serving. You’ll just need to enter the Site IDs during setup.

      How to configure? Select this option. You are not required to specify the Site IDs in this scenario.

4. Additional Filters: Use these filters to narrow the content ingestion scope further. Only records matching ALL of the the specified criteria will be included.
   This is an optional configuration. Moveworks recommend using these filters only if your dataset is very large (i.e. >1million records) so that only relevant content is ingested and served to your employees.

   Currently following filters are supported:
   1. Modified date: Use this filter to include only those content records whose Modified date is after a specified date.
   2. Created date: Use this filter to include only those content records whose Created date is after a specified date.
      Note: We support absolute dates only. Relative ranges (e.g., “last 7 days,” “older than 1 year”) are not supported

Save and Start Ingestion

Once Site selection is configured, you have two options:

• Save: Clicking this will just save the configuration and not initiate the first ingestion crawl. Use this option, if you would want to complete your configuration in multiple sessions/ sittings.
  • Once you click on Save, you will be redirected to the Unily overview screen
  • You will notice a banner that prompts you to Start Ingestion
  • Once you are satisfied with your configuration, you can click on Start Ingestion
  • A confirmation popup will come that provides a summary of the configuration
  • Click on Confirm
  • After you click on Confirm, ingestion will start shortly.
  • For the first crawl to complete, this generally takes anywhere from few hours to 48 hours depending upon the size of the data.
• Save and Start Ingestion: Click this option if you have completed and validated your content selection configuration and you are ready to initiate the first ingestion crawl.

  • A confirmation popup will come that provides a summary of the configuration

  • Click on Confirm

  • After you click on Confirm, ingestion will start shortly.

    Important Note for Admins:

    • It generally takes anywhere from few hours to 48 hours for the first crawl to complete depending upon the size of the data.
    • You can review the status of ingestion via Data Ingestion Viewer and view ingested record in the Indexed Content > Files and Indexed Content > Internal Knowledge screens.

Troubleshooting Connector Validation Failures

This section helps you resolve common issues when validating your Unily connector in Enterprise Search Configuration. Follow the steps below based on the error message(s) you’re experiencing.

Error Message(s):

• “Validation failed: Invalid credentials or missing required scopes.”

Possible Causes:

• Incorrect or missing Client ID/Secret
• Expired credentials
• Wrong Unily environment or base URL

Resolution Steps:

1. Go to Moveworks Setup → Connectors → [Your Unily Connector].
2. Verify the following:
   • Client ID and Client Secret are correctly entered.
   • Base URL matches your Unily Instance API URL (https://<tenant>-api.unily.com).
3. If the issue persists, contact your Unily Support Team to verify the Client ID/Secret credentials.

Missing Required Scopes

Error Message(s):

"Validation failed: Invalid credentials or missing required scopes."

Possible Causes:

• One or more required API scopes not added to the Unily client.
• Access token generated without correct scope grants.

Resolution Steps:

Content

• Missing Scopes:gateway.contentmanagement:read, gateway.graphql, gateway.files.data:read
• How to Test:
  Run the following APIs in Moveworks API Playground:
  • /api/v1/search
  • /api/v1/content/query/{id}
  • /api/v1/files/media/{id}
• Expected:
  All should return 200 OK.
  If any returns 403, ask Unily Admin to add the missing scopes.

Permissions

• Missing Scope:gateway.content.readaccess:read
• How to Test:/api/v1/read-access-assignments
• Expected:200 OK with permissions data.
• If 403: Request Unily Support to add gateway.content.readaccess:read

Groups

• Missing Scope:gateway.security.groups:read
• How to Test:/api/v1/security/groups
• Expected:200 OK with group list.
• If 403: Request Unily Support to add gateway.security.groups:read

Users

• Missing Scope:gateway.usermanagement
• How to Test:/api/v1/users
• Expected:200 OK with user details.
• If 403: Request Unily Support to add gateway.usermanagement