Skip to main content

Integration Builder functionalities

Introduction Search less, find moreEffortlessly locate any document or process, no matter where it’s organised.

Introduction

Search less, find more
Effortlessly locate any document or process, no matter where it’s organised.

We are simplifying time-consuming processes and reducing inefficiencies by enabling you to build your own integrations within minutes. Current integration processes are cumbersome and take a minimum of 100 hours, but with this new freedom, we enhance scalability and efficiency. As a Workspace 365 partner, you can now unlock greater value for your customers. Delivering a solution tailored to their evolving needs not only sets you apart but also positions your partnership as essential to their ongoing success. With the Integration Builder, you're not just offering a product – you're empowering your customers to thrive in an ever-changing digital landscape.

Integrations

An integration consists of two main elements:

  • Authentication

  • Step(s)

Authentication can be set up once, reused, or you can create different authentication methods based on your needs and the complexity of the integration.

Steps simplify the process by allowing you to easily retrieve all the necessary information.

To obtain information, you need to create one or more steps. If necessary, you can query multiple steps to gather the required data. This can be done with a single GET call to an endpoint, or you can build more complex integrations using several steps. For example, first GET all companies. The result from that step will include the company name and ID. In the next step, you could GET a different endpoint to retrieve all employees of that company. This is achieved by querying the API using data from previous steps.

We also provide placeholders (link to placeholders). With these placeholders, you can add, query, and use dynamic data to build your integration.

Integration example

For a example of a integration please look at the article Integration builder example integration (LINK MAKEN)

The first integration

  1. Navigate to Settings -> Integrations -> Integration Builder.
    ​
    ​

    Here you will see an overview of all the (created) integrations. To create a new integration, click New. You can also edit existing integrations; however, keep in mind that you can only edit drafts. It is not possible to edit live versions. If you want to edit a live version, you will be prompted to create a draft for that integration.
    ​

  2. select “New”.

    Here you have a overview of the integration. This consists of three different tabs.

    • General

    • Steps

    • Who has access

      Integrations can be saved as draft, or you can publish

General

As the name suggests, general information is displayed here. Currently, we only support one integration type: Global Search. However, in the near future, we plan to expand this to include different types of integrations. The Global Search integration connects your data to our global search functionality.
​

Within this tab, you can set the name (1), type, icon (2), and colour (2) of the integration. Keep in mind to use clear and consistent naming conventions for the integrations to ensure easier maintenance and usage, as this information will be displayed in the global search.

Authentications

Currently we support two authentication methods.

  • API Key

  • oAuth

Authentications can be used once or reused. On the overview page, you can see which integrations are using your authentication, as well as the authentication type.

Be sure to give it a clear name, so you can easily identify your authentication method within the steps. Then, choose your authentication method.

API Key

API key authentication consists of two fields;

  • Headers

    • Key + Value

  • Query Parameters

    • Key + Value

Add headers to authentication. You can also turn your e.g. headers into secrets by clicking on the lock icon. This cannot be undone!

Optional to add your headers and/pr query parameters.

oAuth

When using oAuth, you need extra information to properly authenticate.

  • Authorization endpoint URL

  • Token endpoint URL

  • Client ID

  • Client secret

  • Scopes (optional)

  • Redirect URL (optional)

When using oAuth as authentication, the user will be prompted to authenticate.

Steps

Within Steps, you can define the actions you want to take. Once you have completed all the required steps, you can map the results in the Result Mapper. The Result Mapper will determine how the information is displayed in the integration type in this case, Global Search.

  1. Click “create new step”

When creating new steps, make sure to use clear step names. In addition to the name, you need to specify the authentication method. You can either create a new authentication or select an existing one. Currently, we support two methods: GET and POST. When using GET, you retrieve information. When using POST, you send information, and a body field will be displayed. The URL is the endpoint yo u want to use. Headers and query parameters are optional.

Headers

Optional headers, depending on the endpoint you want to enclose.

  • Example:

    • Key: “Accept”

    • Value: “text/html”

Query parameters (Optional)

Query parameters are a defined set of key-value pairs attached to the end of a URL, used to provide additional information to a web server when making a request.

  • Example: api.example.com/companies?name=contoso

    • In this case, name is a query parameter.

You can also use placeholders to insert dynamic data into requests. To use placeholders within the steps, you need to use brackets, for example:

  • Key: “Term”

  • Value: “{{SearchTerm}}”

In this case, the call we’re making will be endpoint.url?term={{SearchTerm}}, and {{SearchTerm}} will be replaced with the input from the global search.

See placeholders for all of the available placeholders Click here

Validate

When you have finished creating the step, you need to validate it. The data used as the value for the placeholder (e.g. the value you input in the "search" placeholder) will be used in the validation call.

After validating the step, we will use the validation input for a test call. The result of this test call will be displayed, in this case with a status of 200.

There are various status error codes. Refer to the endpoint documentation you’re trying to connect to for debugging these errors.

Result mapper

Once you have completed all the steps to retrieve the desired information for the integration, you need to map it to the integration type, which in this case is Global Search. Within the Result Mapper, you can select or transform all of the data.

By default the result mapper consist of these fields:

  • Result collection

  • Title

  • Link

  • Date (created/modified)

  • Subtitle 1

  • Subtitle 2

  • Description

Not all fields are display fields which will show information in global search.

Results collection

e Before you can map individual fields, you first need to fill in the result collection. This is the collection of fields that can be used for mapping.

Use the following format: $request["request name"].collection

Replace "request name" with the step name and "collection" with the collection name. In this example, the API returns the collection name: "data".

So we need to use this Result collection;

$request["Get features for company"].data
​
​

  1. After this, click “Validate”.

This will prompt you to input a search query and get a response from the steps you have created. You can expand the step, and the response will be displayed.

Now you can easily start mapping the fields.

Mapping fields

Within global search are some fields which you can use to create the integration.

As you can see in the image, you need a proper title to display your items. In addition, you need a URL, which will be the link the user navigates to when clicking on an item. The date field displays the date/time in a readable format. Additionally, there are Subtitle 1 and Subtitle 2 fields.

  • Title

  • Link

  • Date (created/modified)

  • Subtitle 1

  • Subtitle 2

Description only will be displayed within Advanced search and not in global search.

To start mapping fields, you need to take a look in the response of the step you want to map;
​
​

You can easily map fields from the result collection by entering the field name in the input field of an element. If you want to map a field that is part of an object, you can access it by entering: objectName.fieldName.

You can search for a title. In this case, the response returns the "title". You can choose to display that value as is, or you can transform the data. Each time you make changes to the fields, make sure to validate, so you can immediately see your information being mapped and displayed with your validation search example.

CONCAT("Insight: ", title)

For the full transform functions list click here.

  1. click Done, when you are done with mapping all of the fields,

Edit input data

  1. click “Edit input data”. When you want to make changes to the input data.

Please input the data that will be used as the value for the placeholder. For example, the value you input in the "search" placeholder will be used in the "test" call

Who has acces

You can manage permissions at the integration level, just as you do within the workspace. This allows you to control access and ensure that information is only available to the users who need it. Permissions also depend on the authentication configuration you choose. If you use OAuth authentication, you can scope access based on individual users.

Placeholders

You can press on the icon's bellow to open up a "Placeholders, literals, variables and functions' Screen within the integration builder

Default placeholders

You can use default placeholders to insert dynamic data into requests. The following default placeholders are available:

  • Search term: {{SearchTerm}}

  • Max amount: {{MaxAmount}}

  • First name: {{CurrentUser.FirstName}}

  • Last name: {{CurrentUser.LastName}}

  • Email: {{CurrentUser.Email}}

  • Job title: {{CurrentUser.JobTitle}}

  • Phone number: {{CurrentUser.PhoneNumber}}

Other requests

You can also use placeholders from other requests. To do this, use the following format: {{$request["request name"].fieldname}}

Result mapper

Place holders

Literals, variables, templates and functions (expressions)

In placeholders or fields that are marked with the expression icon , you can use variables, literals and functions (expressions).

  • Literals
    ​

    • A literal is a constant value

    • The following data types are supported: string, integer and boolean

    • Examples:
      ​

      • "Hello"

      • 17

      • true

  • Variables
    ​

    • A variable is a value that can be different based on the context it is used in

    • The following data types are supported: object, array, string, integer and datetime

    • When dealing with an object, you can dereference a field by using either the "dot notation" or the "index notation"

    • When dealing with an array, you can dereference an element using the "index notation"

    • Examples:
      ​

      • SearchTerm

      • CurrentUser.Username

      • CurrentUser["Username"]

      • $request["request name"].items[0]

  • Templates
    ​

  • Functions
    ​

    • A function can be used by using the following syntax: FUNCTION_NAME(arg1, arg2, argn)

    • The amount of arguments and the data type for each argument is specific for each function

    • Each argument can be any expression

    • Examples:
      ​

      • FALLBACK(CurrentUser.Email, CurrentUser.Username)

      • CONCAT("Hello, ", CurrentUser.FirstName)

Available variables

  • $request: an object containing the results from the configured steps, the field names are the names of the configured steps
    ​

    • Example: $request["first-request"]

  • SearchTerm: the term the user wants to search for

  • MaxAmount: the maximum amount of items requested

  • CurrentUser: an object containing the data associated with the current user
    ​

    • Username: the username (UPN)

    • Email: the primary email address

    • FirstName: the first name

    • LastName: the last name

    • JobTitle: the job title

    • PhoneNumber: the phone number

    • Example: CurrentUser.Username

Available functions

  • CONCAT: Combines two strings
    ​

    • Example: CONCAT("Hello, ", CurrentUser.FirstName)

  • FALLBACK: Provides a default string value if the first argument is null
    ​

    • Example: FALLBACK(CurrentUser.Email, CurrentUser.UserName)

  • UNIX_TO_DATETIME: Converts an integer value to a datetime value
    ​

    • Example: UNIX_TO_DATETIME($request["requestname"].unixTimeStamp)

  • JSON: Formats data as a JSON string.
    ​

    • Example: JSON($request["requestname"].category)

  • REPLACE: Replaces the match_to_replace occurrences found in target_string with the replacement string
    ​

    • Usage: REPLACE(target_string, match_to_replace, replacement)

    • Example: REPLACE(JobTitle, "senior", "sr.")

  • CONTAINS: Returns true when the text contains the lookup text. Is case-insensitive by default. There is an option to make it case-sensitive; specify true as the third argument.
    ​

    • Usage: CONTAINS(text, lookup_text)

    • Usage for case-sensitive search: CONTAINS(text, lookup_text, true)

    • When the text is resolved to null, function returns false

    • The lookup_text cannot be null

    • When the lookup_text is resolved to empty string, function returns true

    • Examples:
      ​

      • CONTAINS(CurrentUser.JobTitle, "manager")

      • CONTAINS(CurrentUser.JobTitle, "HR", true)

  • STARTS_WITH: Returns true when the text starts with the lookup text. Is case-insensitive by default. There is an option to make it case-sensitive; specify true as the third argument.
    ​

    • Usage: STARTS_WITH(text, lookup_text)

    • Usage for case-sensitive search: STARTS_WITH(text, lookup_text, true).

    • When the text is resolved to null, function returns false

    • The lookup_text cannot be null

    • When the lookup_text is resolved to empty string, function returns true

    • Examples:
      ​

      • STARTS_WITH(CurrentUser.JobTitle, "product")

      • STARTS_WITH(CurrentUser.JobTitle, "HR", true)

  • ENDS_WITH: Returns true when the text ends with the lookup text. Is case-insensitive by default. There is an option to make it case-sensitive; specify true as the third argument.
    ​

    • Usage: ENDS_WITH(text, lookup_text)

    • Usage for case-sensitive search: ENDS_WITH(text, lookup_text, true)

    • When the text is resolved to null, function returns false

    • The lookup_text cannot be null

    • When the lookup_text is resolved to empty string, function returns true

    • Examples:
      ​

      • ENDS_WITH(CurrentUser.JobTitle, "manager")

      • ENDS_WITH(CurrentUser.JobTitle, "HR", true)

  • EQUALS: Returns true when the provided arguments are equal. Can only be used with primitive values such as strings or numbers. String comparison is case-sensitive.
    ​

    • Usage: EQUALS(argument1, argument2)

    • Examples:
      ​

      • EQUALS(CurrentUser.JobTitle, "Manager")

  • IF: Returns one of two values based on a condition.
    ​

    • Usage: IF(condition, true_result, false_result)

    • When the condition is resolved to true, the true_result is returned; otherwise, the false_result is returned

    • When the condition is resolved to null, it is treated as false

    • Both result values should be of the same type

    • Examples:
      ​

      • IF(EQUALS(CurrentUser.JobTitle, "Manager"), "Approved", "Pending")

      • IF(SearchTerm, SearchTerm, "Default Search")

  • NOT: Inverts the provided condition; true becomes false, and false becomes true.
    ​

    • Usage: NOT(condition)

    • When the condition is resolved to null, it is treated as false

    • Examples:
      ​

      • NOT(EQUALS(CurrentUser.JobTitle, "Manager"))

  • AND: Returns true when both conditions are true; otherwise returns false.
    ​

    • Usage: AND(condition1, condition2)

    • When the condition is resolved to null, it is treated as false

    • Examples:
      ​

      • AND(EQUALS(CurrentUser.FirstName, "John"), EQUALS(CurrentUser.LastName, "Doe"))

  • OR: Returns true when at least one of the conditions is true. If both conditions are false, returns false.
    ​

    • Usage: OR(condition1, condition2)

    • When the condition is resolved to null, it is treated as false

    • Examples:
      ​

      • OR(EQUALS(CurrentUser.JobTitle, "Manager"), EQUALS(CurrentUser.JobTitle, "Product Owner"))


​

Related Articles
Search simplified - Sharepoint sites
Search simplified - Sharepoint Sites and Documents
Guide to Integration Builder
Workspace 365 Integration Builder Guide
Search simplified - Zenya protocols
Did this answer your question?