> For the complete documentation index, see [llms.txt](https://docs.rewst.help/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rewst.help/rewst-documentation/documentation/integrations.md).
# Integrations
{% hint style="info" %}
Were you a Rewst Classic user? The Rewst Agent can now help install Rewst integrations and create custom integrations for you.
{% endhint %}
## What is an integration?
*Integrations* are a core part of Rewst. An integration is the successful linking of the Rewst platform and a separate tool, to allow the free back and forth flow of information between platform and tool. Once you’ve set up an integration, you can use that integration to build automations in the [Workflow Builder](/rewst-documentation/documentation/automations/workflows-in-rewst/rewsts-workflow-builder-how-to-set-up-a-workflow.md), and install [Crates](/rewst-documentation/documentation/crates.md) from our Marketplace. If Rewst doesn’t have a stock, prebuilt integration for your particular tool, you have the option to build one custom. Any tool that has an API can be integrated with Rewst via the Rewst Agent, which is recommended, or manual spec import.
## View integrations in Rewst
Navigate to **Integrations** in the left side menu to access integrations that are both installed and available for installation in the Rewst platform.
## Set up an integration
### Set up Rewst-built integrations
The information needed to set up an integration will differ slightly for each integration. Some may ask for an API Key, while some may require you to list scopes or domains. The same basic principal applies for setting up all integrations: you'll pull information from the app you want to integrate with Rewst, input it into Rewst's configuration page for that integration, and link the two tools.
Each integration's configuration page has menus to map each child organization to its matching external organization in the integrated tool, with the exception of a few rare integrations that don't require organization mapping for their functionality. Once the credential and org mappings are in place, workflows in that organization can call the integrated tool's API without any additional setup. See [this section on org mapping](#what-is-organization-mapping) to learn how to map organizations directly from the set up integration.
The **Settings** panel controls how the integration authenticates and behaves.
* Enter a display name so the integration is easy to identify among your other integrations. Note that the slug is generated from that name and used for API references and workflow serialization.
* Select a credential from the **Credential** dropdown to authorize the connection. In addition to selecting existing credentials you set up prior, you can also choose to set up a brand new credential at this time directly from the integration setup wizard.
* Use the Configuration JSON field if you need to adjust advanced options such as the server URL or template variable values.
* Click the **Credential** dropdown and choose the credential the integration should use.
* Edit the **Configuration JSON** field if you need to change the server URL or other advanced values.
* Toggle **Mock Mode** on if you want the integration to return simulated responses based on OpenAPI schemas instead of calling the real API, which is useful for testing workflows without touching live data.
* Additional menu options will appear for configuration pages in the MSP parent-level organization.
* Click **Save changes** to apply your updates, or click **Reset** to discard them.
An example of an integration configuration page
### Set up your own integrations
{% hint style="info" %}
Were you a Rewst Classic user? Setting up your own custom integrations is now much easier. Ask the Rewst Agent to help you to integrate your preferred tooling. We strongly recommend this method over any attempt to set up a custom integration manually.
{% endhint %}
In addition to Rewst-built integrations, which are created by Rewst's engineering team and automatically available in the Rewst platform, you have the option to make your own integrations for any tool you desire. The Rewst Agent can guide you through how to do this, and complete most of the work for you.
* If you create your own integration, the slug must be unique and not the same as any other integration, even Rewst-built integrations. For example, if making your own ConnectWise PSA integration instead of using Rewst's, you would need to name it `connectwise-psa-2` .
* The Rewst Agent can set up these custom integrations for you. It will direct you to what you need to do on your own, like finding and inputting credentials for the integrating tool, and read spec files to import actions.
* To use Rewst's mock mode, you must know the response structure for your integrating tool's API. It is possible to set up the integration without a known response structure, but mock mode won't work for that integration.
* Rewst-built integrations are designed to work with all Crates released into Marketplace. If you create your own version of an integration that is branded to work with a Crate, for example ConnectWise PSA, you'll need to tell the Rewst Agent that you are using your own integration and want that integration to work with that specific Crate. It can swap what is needed in all the Crate's components.
* Custom integrations must be published at the parent, MSP level in Rewst if you wish to share that same integration down to multiple child orgs. They could be set up on individual child orgs only, but then wouldn't be available to share with other child orgs.
### View installed integrations
Toggle any installed integration to **disabled** in the total integrations list.
Click on any installed integration to open its configuration page. From here you can click to **Uninstall** or **Disable** the integration.
## Update Rewst integrations
Once an integration is installed in Rewst, you'll receive notifications for when it needs an update via a colored dot to the right of the **Integrations** menu in your left side menu of the Rewst platform.
In the integrations list, affected integrations will be moved to a separate **Needs Attention** section of your total integrations list.
* A yellow message to the right of the name of the integration indicates that there's an update available. Click on the integration to choose if you want to accept that update.
* A red message to the right of the name of the integration indicates that your integration may broken or disconnected. If you see this message, you should test the integration and reinstall if any issues are found.
## Map your organizations to finish integrating
### What is organization mapping?
*Organization mapping,* or *org mapping* for short, is the process of connecting each Rewst integration with your child organizations, enabling automations that leverage that integration to work for your customers. This is frequently the last step when setting up your integrations. Once a mapping is saved, Rewst stores the external organization ID for that child org and injects it into every request the integration sends, using whichever parameter the integration flags for org mapping— for example, `x-rewst-org-external-id`. If you update an integration at the parent level, those changes will cascade down to all the child orgs you've mapped to be beneath it.
Org mapping isn't necessary for a few of our integrations because the tool you're integrating with doesn't itself have a concept of organizations. When this is the case for a particular integration, we'll call that out in that integration's setup documentation. Most likely, you will need to org map for every custom integration that you build yourself. If not, the Rewst Agent will let you know.
{% hint style="warning" %}
Organization mapping for Microsoft integrations is slightly different than the process outlined on this page. Refer to our documentation for the Microsoft Cloud bundle.
{% endhint %}
For org mapping to work properly, it's best to aim for having the names of organizations in Rewst match the names of organizations in your PSA. If they don't, you can make the mapping match manually, but having 1:1 names will speed up the mapping process and have you reap the benefits of automation more quickly.
### The Org Mappings menu
An example of the Org Mappings submenu, in an installed integration's configuration page
* The list will contain all child organizations previously mapped in Rewst. If no mapping has been completed, this list will be empty.
* Click **Filter** to narrow the list of external organizations that will be pulled in to Rewst.
* Click **Discover** to search the connected tool for external organizations and suggest which child organizations in Rewst each belongs to. Each suggestion appears as a row recommendation for you to review before accepting it. Org mappings that are already saved aren't included in future discovery recommendations. If no filter is set, discovery returns every org.
* Click **Re-query** to rerun discovery against the tool's system and refresh suggestions. This can only be done after the initial discovery run.
* The **search** field lets you find a specific child org or external org by name.
* Click **Refresh** to reload the current mapping data.
* Click **Save mappings** to commit any pending changes made in the table below.
### How to map organizations: Org mapping
1. Navigate to **Integrations** in the Rewst platform.
2. Select the integration that you want to map from your collection of already set up integrations, or complete the integration configuration setup process for your new desired integration.
3. Scroll down the page to the **Org Mappings** submenu.
4. Click **Discover** to pull customer accounts from your integration. This will sync the potential mapping options for both organizations and companies in the partner tool.
1. If the blank text box turns into a dropdown field, the sync was successful.
2. If accounts are missing, ask the Rewst Agent why.
5. Review the suggestions to ensure that organizations in Rewst and customer names in the integrated tool are aligned. Map the integrated tool's organization on the left to one or multiple Rewst organizations on the right using the drop-down selector.
6. Double-check all mappings, especially if you have multiple pages of organizations. By default, only the first 10 organizations will be listed.
7. Click **Save Mappings** to finalize the connections.
{% hint style="info" %}
If you uninstall an integration and reinstall it again, you won't need to redo your org mapping. Rewst will have this information stored and will repopulate it into the new installation.
{% endhint %}
## Actions in Rewst
{% hint style="info" %}
Were you a Rewst Classic customer? Rewst no longer documents action endpoint tables in our integration documentation. The Rewst Agent is your up-to-date source for what endpoints are available to you for integrations. For Rewst-built integrations, simply ask it for your desired endpoint to achieve your action goal. For custom integrations, feed it the spec, and as part of the integration building process it will pull in all actions available from that file.
{% endhint %}
Learn more about action nodes in our documentation [here](/rewst-documentation/documentation/automations/nodes/nodes-actions.md).
Once an integration is set up in Rewst, actions for that integration will be pulled into your actions list in the [Workflow Builder](/rewst-documentation/documentation/automations/workflows-in-rewst/rewsts-workflow-builder-how-to-set-up-a-workflow.md#drag-the-action). This applies to both Rewst-built integrations and integrations you set up custom with your own spec file.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.rewst.help/rewst-documentation/documentation/integrations.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
