Set Up a Connector
Walk through the four steps of Connector Setup, from choosing a system to activating the connection, with what each system asks for.
Connector Setup creates the link between one of your systems and QortexOS. Its subtitle reads "Connect a provider in a few steps; the first sync runs on activation." It is a four-step wizard: Connection, Identifiers, Authentication, and Review & activate.
Before you start, you need two things:
- Connector-creation access. Without it the screen reads You need connector-creation access, with the line "Ask an administrator for data integration create access to set up connectors."
- The sign-in details for the system you are connecting. What that means depends on the system: an API key or token created for a service account, or an administrator login you can use to approve access when the wizard sends you to the provider. The table further down lists what each system asks for.
The four steps
Choose the system. The Connection step, headed Choose a provider, asks for one thing: the system, chosen from grouped cards. Its helper reads "Pick the system to connect; its type is set automatically." Nothing else is asked here. The summary panel beside the wizard notes that "The connector name, sync schedule, and rate limits are set automatically."
Identify your instance. The Identifiers step, headed Instance details, reads "Identify your instance so the connection reaches the right place." What it asks for depends on the system: a company domain, a server host, a tenant name, an account ID, a region, or a platform. Some systems ask for nothing here. For systems you connect by approving access at the provider, some identifiers are filled in for you after you connect.
Provide access. The Authentication step reads "Provide access so the platform can read your data." It takes one of three shapes, described in the next section: credentials you enter in QortexOS, an approval you give at the provider, or, for QuickBooks Desktop, a connection the platform provisions.
Review and finish. The Review & activate step lists everything you entered and asks you to "Confirm the configuration, then activate or save as a draft." Choose one of the two finishing actions below.
A summary panel titled Your configuration sits beside the wizard the whole way through and fills in as you go. Rows you have not reached yet read Not set, and the Credentials row reads "number values entered" rather than showing what you typed. The footer carries Back and Next, reads Working... while a step is loading, and carries Exit setup on every step. You can go back into any step you have already completed.
Three ways to provide access
Which one you get is decided by the system you chose.
Credentials you enter in QortexOS
Most systems ask you to enter one or more values on the Authentication step: an API key, a client ID and secret, a username and password, or a token. Each value is masked as you type, with Show value and Hide value beside it. The values are verified by a live connection test when you activate, and stored by the platform.
Approval at the provider
For systems that use an account connection, the step shows a single button, Connect provider, with the helper "You will be sent to the provider to approve read access. Credentials stay with the provider; the platform stores only the connection grant." and the line "After approval you will return here to finish the setup."
- For Xero, Sage Accounting, and FreshBooks, coming back opens a Finish the connection step that asks you to "Choose which provider organization this connection should read." Pick one from Available organizations and select Finish connection.
- If you decline at the provider, the step reads Connection not approved, with "The provider reported that access was not granted. You can start the connection again at any time."
- If something goes wrong, it reads The connection could not be completed, with "Something went wrong while completing the provider connection. Start the connection again; if it keeps failing, contact support."
- If the approval cannot be matched to a connection, it reads Connection not found, with "The connection created by the approval could not be loaded. Open the connector console to check its status."
Provisioned by the platform
QuickBooks Desktop asks for no vendor credential at all. The platform provisions the connection and hands you what the QuickBooks Web Connector needs. That flow has its own page: QuickBooks Desktop.
Systems that offer two methods
HubSpot and Pipedrive offer both a token and an account connection, so their Authentication step opens with an Authentication method picker: Private app token or Connect account for HubSpot, API token or Connect account for Pipedrive. The token method is selected by default.
What each system asks for
| System | Identifiers step | Authentication step |
|---|---|---|
| Autotask | Nothing. The API zone is worked out from the username. | API username ("The API user email created for this integration."), API secret, Integration code |
| BambooHR | Company domain ("The subdomain of your BambooHR account (yourcompany.bamboohr.com).") | API key ("Create the key for a dedicated service account with read access."). That account must be able to view compensation, job information, and employment status, or pay fields import empty. |
| ConnectWise Automate | Automate server host ("The hostname of your Automate server, without https://.") | Client ID ("The ConnectWise developer Client ID registered for this integration."), Username, Password, and an optional Two-factor passcode ("Only when your Automate server enforces 2FA for API users.") |
| ConnectWise Manage | Company ID, Site host ("Your ConnectWise Manage API host, e.g. api-na.myconnectwise.net.") | Public key, Private key, Client ID |
| Datto | Platform: pinotage, merlot, concord, vidal, zinfandel, or syrah ("The Datto RMM platform your account runs on (shown in your Datto URL).") | API key, API secret |
| FreshBooks | Account ID, filled in after you connect, and an optional Business ID ("Optional: a specific FreshBooks business to read.") | Connect account |
| Halo | HaloPSA tenant ("Your HaloPSA tenant name (the part before .halopsa.com).") | Client ID, Client secret |
| HubSpot | Nothing. | Private app access token (default) or Connect account |
| NetSuite | NetSuite account ID (shown under Setup, then Company Information), Integration client ID, Certificate ID | Private key (PEM) ("Paste the full PEM private key, including the BEGIN and END lines.") and an optional Signing algorithm, PS256 or ES256 |
| NinjaOne | Region: us, eu, or oc | Client ID, Client secret |
| Pipedrive | Nothing. | API token (default) or Connect account |
| QuickBooks | Nothing. | Provisioned by the platform. See QuickBooks Desktop. |
| QuickBooks Online | Company (realm) ID, filled in after you connect, and an optional Environment, production or sandbox | Connect account |
| Sage Accounting | Business ID, chosen after you connect ("Filled automatically after you connect your Sage account.") | Connect account |
| Sage Intacct | Nothing. | Client ID, Client secret, Refresh token |
| Salesforce | Instance URL ("Filled automatically when you connect your Salesforce org.") | Connect account |
| SimpleSat | Nothing. | API key ("The key needs read access to surveys and responses.") |
| SmileBack | Nothing. | Client ID, Client secret, Username, Password ("A dedicated service login with read access is recommended.") |
| Xero | Xero organisation ID, chosen after you connect | Connect account |
The two ways to finish
For systems whose access you enter in QortexOS, the connector is created at the last step, and only then.
- Activate connector creates the connector and runs a live connection test. The step's helper says "Activate runs a live connection test against the provider before saving." If the connector cannot be created, an alert titled Could not create the connector appears with the reason, such as "Storing the connector credentials failed; try again or contact support", a message that the credentials were rejected, or one that the provider could not be reached. The connector is not created, and the alert clears with Dismiss.
- Save as draft creates the connector without a test. Its helper reads "Saves the connector paused, without a connection test."
Exit setup is on every step. For systems whose access you enter in QortexOS, nothing is stored until you finish on Review & activate. For an approval at the provider, the platform stores the connection grant as soon as you approve, and a QuickBooks Desktop connection is created on the Authentication step itself.
What happens next
The wizard is replaced by a Connector created panel carrying a Connection tested or Saved as draft badge. That panel is where you choose the data sets and start the first run. Continue with Run your first sync.
Related
Supported Systems
The systems you can select in Connector Setup, grouped by the categories the provider picker uses.
QuickBooks Desktop
Connect QuickBooks Desktop through the QuickBooks Web Connector, where available. What the wizard hands you, what to do on the QuickBooks computer, and how the connector behaves afterward.