Ngentix

FAQ

The questions we are asked most. The console's Help is written from the same source, so the two cannot disagree.

Guides

Build a flow

A flow moves one kind of record, such as contacts, between a system your customers use and your product. Build one here, switch it on, and your customers can subscribe to it.

A flow is a line between two systems HubSpot, the source, and your product, the destination, are two stations joined by an orange line labelled Contacts, every hour. Four steps sit under it, in the builder's order: pick the Source and Destination, with your product as one end; choose What moves; choose When it runs; then Save flow to keep it off, or Activate to turn it on. Customers see a flow once it is on and has a Description. Source Destination Hs Ac HubSpot Your product Contacts every hour 1 Source → Destination Your product is one end 2 What moves fields; we suggest matches 3 When it runs a schedule 4 Save flow or Activate kept off, or saved and on Customers see a flow once it is on and has a Description.

Start from a prebuilt flow

Many pairs are already mapped. On Flows, open the Prebuilt catalog tab, pick the two systems and press Use this. See Start from a prebuilt flow.

Build your own

  1. On Flows, press Create a new flow.
  2. Pick the Source and the Destination. Pick one third-party system and your product fills the other end. Press Swap to reverse the direction.
  3. Under What moves, pick a resource on each end. The builder matches fields it can; check them and add any it missed.
  4. Choose When it runs: every 15 minutes, every hour, every day, only when you run it, or when a condition is met.
  5. Press Save flow to keep it off, or Activate to save it and switch it on. If something is missing, the bar says what.

The builder names the flow from what you picked; click the name to change it. Customers never see that name. They read the flow's Description.

Let customers see it

A flow shows on your subscribe page once it is on and has a Description. See Let customers subscribe to a flow.

If the other system needs an app from you, the flow can't be switched on until you register one: after Save flow the builder asks first, with Register with <System>, and Activate stays greyed. See Register an app.

Related

Register an app

When your customers connect a system by signing in, they approve your app on that provider's own site. Register that app once, and every customer can connect that system.

What your customer does, with an app you registered One line of five stops. Stop 0, dashed and set apart, is you, once: register your app. Then your customer picks a flow on your page, pays and creates an account, signs in at the provider and approves your app, and is connected. Stop 3 is drawn as a square because it happens on the provider's own approval screen. 0 1 2 3 4 You · once register your app Picks a flow on your page Pays and creates an account Signs in at the provider, approves your app Connected data starts moving You appear once, before any customer arrives. Stop 3 happens on the provider’s own approval screen.

Do I need one?

On Connectors, the filter OAuth app from you lists the systems that need an app. For the rest, Customer-provided auth, your customers paste their own key. Their Setup tab says Nothing for you to register.

Register it

  1. Open Connectors, choose the system, and stay on its Setup tab.
  2. Press Open <System> developer site and create an app there.
  3. Give the provider the redirect address shown. Press Copy to take it.
  4. Paste back the Client ID and Client secret it gives you, and press Register app.

The system now shows Registered in your Connectors list, and its Setup tab says Your app is registered. Its page reads Registered · not tried until you test it. The secret is encrypted and never shown again.

Test it as a customer would

  1. Press Check app setup to ask the provider whether it knows your client ID. Then press Connect as a customer: you sign in with your own login, the way a customer will, and see the approval screen they will see. See Test a connector before your customers do.

To replace a lost secret, create a new one on the provider's site and press Replace.

Related

Fix an interrupted customer

When a customer's data stops moving, Home tells you why and who can fix it. Screens call this Interrupted; see What each status means. Most fixes are one button.

Who fixes what Three rows. Your customer: their sign-in ended, so press Compose re-connect emails and they sign in again. You: something on your side, with Set them up, Open mapping and Investigate. The provider: briefly down, and it retries by itself; Open failed runs shows the runs that failed. Your customer sign-in ended Compose re-connect emails they sign in again You on your side Set them up Open mapping Investigate The provider briefly down Open failed runs It retries by itself

Find the problem

  1. Open Home. The Needs you column lists each problem as a card, worst first.
  2. Click a card's title to see why it happened, which customers it affects and which flows.
  3. Press the card's button. What it does depends on who can fix it.

What each card asks of you

  • Customers must reconnect — their sign-in expired or was revoked, and only they can approve again. Press Compose re-connect emails; see Ask customers to reconnect.
  • Systems are waiting on your setup — a flow needs an app you haven't registered. Press Set them up; see Register an app.
  • Credentials will not refresh — the provider rejects your app's secret. Press Check app credentials and replace it on the system's Setup tab.
  • Flows are dropping a mapped field — press Open mapping to go to the flow, then Edit this flow and fix the field.
  • Connections are interrupted and we cannot say why — press Investigate to see the last error. Don't send a re-connect link until you know it's a sign-in problem.
  • Elevated errors or upstream changes — the provider is failing or has changed. Press Open failed runs or Open the change. Flows retry by themselves.

For one customer

Open Customers and choose them. You see their connections, flows and recent activity, with Copy connect link and, when a connection is interrupted, Compose re-connect email. Customers whose flows can't run are grouped under Data has stopped.

When we email your customer for you

When a customer's sign-in stops working, we email them a link to reconnect, sent as "your company via Ngentix" so their replies come to you. You get an email saying we did, with the same link. We only write to an address the customer has verified, and we send a reminder every few days while it stays interrupted, at most five.

If many connections break at once (a provider outage), we email no customers that round and tell you instead, so nobody is flooded.

To stop these emails, untick Email a customer when their connection breaks under Settings → Workspace. You still hear about every break.

Related

Tasks

Set up QuickBooks — test keys, live keys and the redirect address

To let your customers connect QuickBooks, you create an "app" once on Intuit's developer site and give Ngentix two things from it. Intuit gives every app two sets of keys: one for testing and one for real customers.

In plain terms

  • Test keys (Intuit calls them Development) only work with a pretend QuickBooks company that Intuit gives you for free, a sandbox company. Nothing real is touched. Use these while you try your flows.
  • Live keys (Intuit calls them Production) work with your customers' real QuickBooks. Intuit shows them only after you answer a short questionnaire about your app and Intuit approves it, so start that early.
  • The redirect address is where QuickBooks sends a person back after they sign in. Intuit only sends people to addresses you've listed, and it keeps a separate list for test and for live. Add Ngentix's address to both.
  • Ngentix holds both sets. Setup has a Production keys slot and a Test keys slot. Your customers always connect with the production keys. Your own Connect as a customer can use either, so you can keep testing against your sandbox company while real customers are live.

Step by step

  1. In Ngentix, open Connectors → QuickBooks. On Setup, press Copy next to the redirect address. You'll paste it twice.
  2. On Intuit's developer site, sign in and choose My Hub → App dashboard. Open your app, or create one for QuickBooks Online Accounting. If you have more than one Intuit account, use the one that owns this app everywhere below.
  3. Open Settings → Redirect URIs. On the test list (shown first), press Add URI, paste the address, and save. Then choose Production and do the same.
  4. Open Keys and credentials, choose Production (after Intuit approves the questionnaire), and turn on Show credentials. Copy the Client ID and Client secret into Ngentix's Setup and press Register app. These are your production keys.
  5. Back on Intuit, choose Development and copy that pair too. In Ngentix, press Add test keys and paste it.
  6. Press Check app setup on each pair. Then, under Connect as a customer, choose Test keys and sign in with your sandbox company to see what your customers will see.

Waiting on Intuit's approval? Put the Development pair in the production slot for now, and swap in the Production pair when it arrives.

The technical detail

  • Development credentials authorize against sandbox companies only, and API calls for them go to sandbox-quickbooks.api.intuit.com. Production credentials authorize live companies at quickbooks.api.intuit.com. A key set used against the other host is refused.
  • The redirect URI must match exactly: same scheme, host and path, no trailing slash. Production URIs must be https and can't be IP addresses. localhost is allowed on the Development list only.
  • Each app's Development and Production URI lists are separate. Keep entries your own tools use; adding Ngentix's doesn't replace them.
  • Intuit shares one sign-in page for both key sets (appcenter.intuit.com/connect/oauth2), so Ngentix needs no separate test sign-in address. Only the keys and the API host differ.
  • A sign-in made with your test keys is pointed at sandbox-quickbooks.api.intuit.com from the start, so its first read goes to your sandbox company.
  • Intuit's error "The redirect_uri query parameter value is invalid" means the address isn't on the list for the key set in use.

Related

Set up Stripe — your Stripe App, test links and live links

To let your customers connect Stripe, you make a Stripe App once, under your own Stripe account, and give Ngentix two things from it. Your customers then sign in to Stripe and approve your app, and that is all they do.

⚠ Until Stripe publishes your app, only Stripe test accounts can sign in. Your real customers can't connect Stripe until Stripe has reviewed and published it (Publish app on your app's page in Stripe). Submit it as soon as your test sign-in works — the review is Stripe's, on Stripe's timeline.

In plain terms

  • A Stripe App is how Stripe lets another company work in a customer's Stripe account. Stripe retired the older way (OAuth settings under Connect), so if you went looking for those settings and couldn't find them, that's why.
  • You make the app with Stripe's command-line tool, not in the dashboard. It's a short file that names your app, lists what it may read and change, and lists where Stripe may send people back to. You upload it once.
  • It's your app, under your name. Your customers see your app's name when they approve it. Ngentix never owns or changes it.
  • Before Stripe reviews it, you can try it with up to 25 test accounts using the links under External testing → Test OAuth. Before real customers can install it, Stripe reviews it for the App Marketplace. Start that early.
  • Ngentix holds two sets. Setup has a Production keys slot (for your customers) and a Test keys slot (for your own Connect as a customer).

Step by step

  1. In Ngentix, open Connectors → Stripe. On Setup, press Copy next to the redirect address.
  2. Install Stripe's command-line tool and its app plugins, then sign in as the Stripe account that will own the app. Stripe asks which environment to give the tool: choosing your test environment is enough to start.
npm install -g @stripe/cli
stripe plugin install apps
stripe plugin install generate
stripe login
  1. The first time, Stripe asks you to accept the Stripe Apps Agreement. The next command stops with a link to it; open the link, accept, and run the command again.
  2. Make the app in a new folder of its own, outside any other project, and open it. Stripe won't accept a public app whose name includes "Stripe", "app", "free" or "paid".
stripe generate app my-company-stripe --id com.mycompany.ngentix --display-name "My Company"
cd my-company-stripe
  1. The app needs no screen inside Stripe, so delete the src folder the command made. Add a 300 × 300 PNG icon, then make stripe-app.json say this. Put the address you copied in allowed_redirect_uris (Stripe accepts https addresses only), and list what your flows read and change. A _write permission includes reading; ask only for what your flows use, because your customers see this list when they approve. This example covers customers, products and prices:
{
  "id": "com.mycompany.ngentix",
  "version": "0.0.1",
  "name": "My Company",
  "icon": "./icon.png",
  "distribution_type": "public",
  "stripe_api_access_type": "oauth",
  "sandbox_install_compatible": true,
  "allowed_redirect_uris": ["<the redirect address you copied>"],
  "permissions": [
    { "permission": "customer_write", "purpose": "Keep your customers in step with My Company." },
    { "permission": "product_write", "purpose": "Keep your products in step with My Company." },
    { "permission": "plan_write", "purpose": "Keep your prices in step with My Company." }
  ]
}
  1. Upload it. Stripe checks the file first and names anything it won't accept.
stripe apps upload
  1. In Stripe's dashboard, open Developers → Created apps and choose your app. On Details, find External testing. If it shows no version, press Set external test version and choose the one you uploaded. Leave Access on Anyone with the link (the other choice, Closed, stops testing). Open Test OAuth: it has a Live mode link, a Test mode link and a Sandbox link. Copy the Test mode link.

The Install links higher up on the page, under the warning "These OAuth links will not be active until the app is published", are your app's public links. Don't test with them: they do nothing until Stripe publishes the app. 8. The link you copied holds the two values Ngentix needs. It looks like this:

https://marketplace.stripe.com/oauth/v2/chnlink_…/authorize?client_id=ca_…&redirect_uri=…

Back in Ngentix, open Connectors → Stripe → Setup. In Client ID, paste the part after client_id= (it starts ca_, up to the &). In Secret key, paste your Stripe account's test mode secret key (sk_test_…). Open Advanced (optional) and, in Authorization URL (override), paste the link up to and including /authorize — until Stripe publishes your app, people sign in at your app's own address. Save. If your live values are already saved, use Add test keys for these instead. Then Connect as a customer and sign in with a Stripe test account other than the one that owns the app. 9. When you're ready for real customers, press Publish app to send it to Stripe for review. After Stripe publishes it, replace the values in Setup with the Live mode link's client ID and your live secret key (sk_live_…), and clear Authorization URL (override) — a published app signs people in at Stripe's own address. Each link has its own client ID, so take each from its own link.

The technical detail

  • Customers sign in at marketplace.stripe.com/oauth/v2/authorize with your client ID once the app is published; before that, at the app's own …/oauth/v2/chnlink_…/authorize address from Test OAuth. Ngentix exchanges the code at api.stripe.com/v1/oauth/token, using your secret key as the client secret.
  • A Stripe App's access is set by the permissions in its manifest, not by a scope on the sign-in link, so Ngentix asks for no scope.
  • Access tokens last an hour. Each refresh returns a new refresh token, which Ngentix stores at once; a refresh token unused for a year expires.
  • The client ID and the secret key must match the link the customer used: the Live mode link's client ID with your live secret key, the Test mode link's with your test mode secret key. A Sandbox link install uses your app's managed sandbox key instead, which Stripe makes only for an app uploaded from your live account. Use a full secret key, never a restricted key (rk_…): Stripe refuses those here.
  • External test links from an app uploaded from a sandbox or test-only account install only on other sandbox or test-only accounts.
  • Stripe's error about a redirect means the address isn't in allowed_redirect_uris exactly as Setup shows it: same scheme, host and path, no trailing slash. Change the manifest and upload again.

Related

Test a connector before your customers do

A connector needs two things to work for your customers: your app has to be set up right on the provider's side, and the sign-in has to work end to end. Ngentix tests each one separately, so you know which part to fix.

The two tests

  • Check app setup asks the provider whether it knows the client ID you pasted. Nobody signs in and nothing is created. It takes a second.
  • Connect as a customer walks the real sign-in your customers will see: the provider's approval screen, your app's name on it, and the trip back to Ngentix. You use your own account, never a customer's.

Run them in that order. Check app setup catches a mistyped or wrong client ID in a second. Connect as a customer proves everything else.

What each result means

  • client ID recognised. The provider knows your app. Many providers, Intuit included, only check the secret and the redirect address when a real person signs in, so this does not prove those yet. Connect as a customer does.
  • not recognised. The provider does not know this client ID and secret. Copy both again from your app on the provider's developer site, save, and check again.
  • couldn't tell. The provider answered in a way we can't read reliably. Its exact answer is under the result. This is never shown as a pass. Connect as a customer tests the whole sign-in instead.

Saving a new client ID or secret clears Check app setup, because its result described the old app.

Test keys and production keys

Some providers give you two sets of keys: a test set that only reaches a pretend company, and a live set for real customers. Intuit calls them Development and Production.

Setup holds both:

  • Production keys are what every customer connects with.
  • Test keys are optional and only used by your own Connect as a customer. Customers never use them, so saving or changing them can't affect anyone who is already connected.

With test keys saved, Connect as a customer asks which pair to sign in with. It starts on Test keys, and a QuickBooks sign-in made with them goes straight to your sandbox company. The result says which pair you used.

Once a connector passes, you can test any flow that uses it: see Test a flow before your customers use it.

Related

How each connector is tested

Every connector's Overview says how you test it against the provider itself, under How you test it:

  • A separate test environment. The provider runs a test copy of its service, and test sign-ins only ever reach it (QuickBooks, Salesforce).
  • A test account on the normal service. The provider has no separate copy, but gives you test keys or a free test account whose data is yours to change (Stripe test mode, a HubSpot developer test account, a Shopify development store).
  • Not yet checked. We haven't confirmed this provider's own test option yet. That is a gap on our side, not a dead end: tell us and we will look.

Each answer also says where it comes from. From the provider's docs means we read it in the provider's developer documentation. Confirmed by a real test means a test sign-in went through it and read data back, with the date it last did. A Connect as a customer made with Test keys confirms it.

Test a flow before your customers use it

A test runs one flow for real, with your own test accounts, so you see it work before any customer does. You set it up once. After that, testing any flow is one button.

Set it up once

  1. The other system's test sign-in. Open Connectors → the system (for example QuickBooks Online) → Setup and press Connect as a customer. Sign in with your own test account, such as a QuickBooks sandbox company. See Test a connector before your customers do.
  2. Your product's test address and key. Open Connectors → Your product connectors → your product, and under For testing flows press Add test address. Give the address of a test copy of your product, such as https://staging.your-product.com, and a key for it. Saved once; the key is never shown again.

Test a flow

Open the flow and press Test this flow, then Run test. The test:

  • reads up to 5 records from the source,
  • really writes them to the destination,
  • shows each record: what was sent, whether it was written or refused, and, when refused, the other end's own words.

Above the tabs the flow then says Tested, with the date and how many records were written. A flow nobody has tested says Never tested.

What a test never does

  • It never uses a customer's connection, only your own test sign-in.
  • It never writes to your live product, and never sends your live key. A test address that is your live address is refused.
  • It is not a run: it doesn't appear in Runs or Activity, and nothing schedules it. Every customer's flow keeps running as it was.

You can run 10 tests a day. The last 10 tests of each flow are kept.

When a test refuses to start

  • "Connect as a customer first": step 1 above isn't done for that system.
  • "Add … test address and test key first": step 2 above isn't done.

Related

Fix "The redirect_uri query parameter value is invalid" in QuickBooks

QuickBooks sends a person back to Ngentix after they sign in, but only to an address your Intuit app lists. If the address is missing, Intuit stops the sign-in with "The redirect_uri query parameter value is invalid". Add the address once and every customer can connect.

  1. In Ngentix, open Connectors → QuickBooks. On Setup, press Copy next to the redirect address.
  2. Go to the Intuit developer site and sign in with the account that owns your app. If you have more than one Intuit account, check which one does: its app's Client ID matches the one you registered in Ngentix.
  3. Open your app, then Settings in the left menu, then the Redirect URIs tab. Intuit moved this out of Keys and credentials; it isn't there.
  4. Choose Development to test with a sandbox company, or Production for real customers. Each keeps its own list, so add the address to each one you use.
  5. Press Add URI, paste the address, and save. It must match exactly: the same https, no trailing slash.
  6. Back in Ngentix, press Connect as a customer. You should reach Intuit's Connect screen.

Keep any addresses already on the list. Your own test tools may rely on them.

Related

Glossary

Glossary

  • Activate — switch a flow on, so it runs and customers can subscribe. On a flow's row in Flows, or in the builder.
  • Activity — every run of every flow, newest first, with a time, the customer and the result. Click a run for its ID and details. Flows → Activity.
  • API key — a secret key your own server uses to call Ngentix. Create one under Settings → API keys.
  • Approval screen — the provider's own page where your customer signs in and allows access. It shows the name of your app.
  • Can't activate — a flow is missing something it needs, usually a connection or your app with a provider. The status names it; fix that, then Activate.
  • Circuit open — we stopped calling a provider that kept failing, for a short while. Your flows retry by themselves.
  • Connection — one customer's live link to one system: their sign-in or key, stored by us. A flow needs one at each end.
  • Connector — one system you can move data to or from, such as HubSpot or QuickBooks. Your product is a connector too.
  • Connector directory — a public list of the systems you support. Nothing is sold there. Under Settings → Public pages.
  • Customer — a business that uses your product. They subscribe to, and pay for, the flows they want.
  • Customer-provided auth — a system your customers connect by pasting their own key. Nothing for you to register.
  • Data has stopped — on Customers, the customers whose flows can't run, for example because their sign-in expired. A customer who removed a connection is not here: that was their choice.
  • Fields — which field on one side fills which field on the other; also called field mapping. On a flow's Fields tab.
  • Flow — one kind of record moving between two systems, on a schedule or when you run it, for every customer who subscribes.
  • Interrupted — data stopped moving for a customer; the reason sits beside the word. All the status words are in What each status means.
  • Lapsed — a customer who used flows before and no longer has a live connection. A filter on Customers.
  • Removed by customer · Removed by you · Removed — a connection someone chose to switch off, and who: the customer, your team or your server, or Removed when it happened before we recorded who. Never a fault. See What each status means.
  • Needs you — the cards on Home for problems only you can act on, worst first, each with one button.
  • Not set up — a system that still needs your app before customers can connect it.
  • OAuth app from you — a system your customers connect by signing in, so you register one app with the provider first.
  • Paused — a flow stopped for one hour. It resumes on its own, or press Resume. Customers keep paying, and new visitors to your page see "undergoing maintenance".
  • Prebuilt flow — a flow we have already mapped, ready to use as it is or to adjust. Under Flows → Prebuilt catalog.
  • Publishable key — the one key that is safe in a web page. It only starts connections, for the connect button.
  • Reconnect — a customer approving access again after it expired or was revoked. Only they can do it.
  • Redirect address — where the provider sends a customer back after they approve your app; some providers call it a redirect URI. You copy it into your app's settings.
  • Registered — your app with that provider is saved, so customers can connect it. A system's page says Registered · not tried until you test it with your own sign-in.
  • Resource — the kind of record a flow moves: contacts, invoices, tickets.
  • Run ID — the id of one run, shown when you click it in Activity. Quote it to Ngentix support and we can find everything about that run.
  • Running · Needs attention · Interrupted · Idle — the map's states. Running: moving data. Needs attention: waiting on you. Interrupted: data has stopped. Idle: on, but nobody has subscribed yet.
  • Stop now — an emergency stop of a flow for every customer at once, with a reason they see. Lift the halt ends it; switching the flow back on is a second step.
  • Subscribe page — your page where customers choose and pay for flows. Its link is under Settings → Public pages.
  • Synthetic data — made-up but realistic records from the practice systems (Sandbox CRM, HRIS and Support). Never billed.
  • Trigger — what makes a flow run: a schedule, a condition, or you pressing run.
  • Withdraw — take a flow off your subscribe page. Current customers run to the end of the period they paid for. Not permanent.
  • Your app — the app you register with a provider so your customers approve you when they connect.
  • Your product — your own system, the one your customers' data moves to and from. Under Connectors → Your product connectors.

Views

What API keys are for

API keys are how your own server calls Ngentix. You need one only if your code calls the API; the console alone needs none.

Using them

  1. Under Settings → API keys, type a Name and press Create key. Make one per place that calls us, so revoking one never takes down the others.
  2. Copy the key when it is shown. It is shown once; after that the list shows only its prefix.
  3. To replace a key, press Rotate. To stop it working, press Revoke.

Lost a key? Rotate it, or create a new one and revoke the old.

The publishable key is different: it is safe in a web page and only starts connections. See When to use a publishable key.

The app you register with each provider lives on that system's Setup tab, not here.

Related

What Connectors is for

Connectors holds the systems you support and your own product. Pick the systems you support; register an app for any that need one.

Two ways your customers connect a system Two rows. OAuth app from you: you register one app with HubSpot, once, and each customer signs in on HubSpot and approves your app. Customer-provided auth: each customer pastes their own key for a system such as Greenhouse, and there is nothing for you to register. OAuth app from you Ac Hs You register one app with HubSpot, once Your customer signs in on HubSpot, approves your app Customer-provided auth Ac Nothing for you to register Gh Your customer pastes their own key

What's on it

  • Third-party connectors — every system we connect to. You support lists the ones you picked; Customers can buy shows which have a flow on your page. Customers only see systems with a flow on your page.
  • Your product connectors — your own product. See What Your product is for.
  • + Add connectors adds systems to You support. Build a flow or Add a flow on a row starts a flow with it.
  • The filter What it needs splits OAuth app from you (you register an app once) from Customer-provided auth (nothing to register).

A system's own page

Open a system for its Setup, Overview and Flows tabs. Setup shows what your customer does, then how to register your app and test it twice: Check app setup (does the provider know your app?) and Connect as a customer (does the whole sign-in work?). A key system says Nothing for you to register and offers Try it with my key. See Test a connector before your customers do.

Related

What Your product is for

Your product is the system your customers' data moves to and from. Tell us how to reach it once, and every flow can read from it and write to it.

How Ngentix calls your product Ngentix calls your product with our key on every call. An example request, GET https://api.acme.com/customers/acme-42/contacts, is labelled: https://api.acme.com is the Address, and acme-42 is One customer is — the id that says which of your customers the call is about, carried in the path, a header or a query. Our key Ac sent on every call · stored, encrypted GET https://api.acme.com /customers/ acme-42 /contacts Address where we call One customer is in the path, a header or a query

Set it up

On Connectors → Your product connectors, under How we reach it:

  1. Address — where your API lives.
  2. Our key — the key we use to call you. It is stored encrypted; press Replace to change it.
  3. One customer is — where your API expects the customer's id: In the path, In a header or In a query. This is the one people get wrong; the example request shows the result.
  4. Where we check the key is optional. Without it, we test the address itself.
  5. Press Test the connection.

The stamp says Live once it works. See flows lists the flows that use it.

Related

What Flows is for

Flows lists every flow you have, grouped by the system it connects to, and lets you switch each one on or off.

What's on it

  • Your flows, the Prebuilt catalog and Activity, as three tabs.
  • Each row shows the route, when it runs, its status, how many customers it runs for, its last run and the records it moved in 7 days.
  • Show: Needs attention narrows the list to the flows that need you.
  • One button per row: Activate, Pause, Resume or Lift the halt, whichever fits the flow's state.
  • Create a new flow and Browse the prebuilt catalog sit at the foot.

Can't activate means the flow is missing a connection it needs: an app you register with the provider, or your own product. The status names it.

Open a flow for its fields, customers, runs and settings. Withdraw, Stop now and Delete are on the flow's own page.

Activity: every run, in one place

Activity lists every run of every flow, newest first, so you can answer did anything fail today? without opening each flow.

  • When is the time the run started, in your time zone.
  • All runs · Failed · Didn't run narrow it, each with a count. Failed means the run reached a system and something went wrong. Didn't run means it never started, usually because the customer isn't connected.
  • Choose one flow, one or more customers, and Today, 7 days, 30 days or 90 days.
  • Click a run to open its details: the Run ID, the flow and customer IDs, when it started and finished (in UTC), how long it took, the records it moved or dropped, and what started it. Copy puts an ID on your clipboard. Quote the Run ID to Ngentix support and we can find the rest.
  • Download CSV saves the runs you're looking at, up to 30 days, to hand to support or a spreadsheet.
  • A deleted flow's runs stay, marked (deleted).

Home's problems link here narrowed to Failed (a problem's drawer also to the customers it affects), and a customer's page links to their runs.

Related

What Customers is for

Customers lists the businesses using your flows and the state of their connections.

What's on it

  • Data has stopped groups the customers whose flows can't run, above Running. The group only appears when somebody is in it.
  • On a stopped row, Compose re-connect email opens a ready-written message. Open it in your mail app or copy it; Ngentix doesn't send it for you.
  • A customer who subscribed but never connected gets Send connect link. With no contact on file it is disabled and says no contact on file.
  • Active · Lapsed · All is a filter, not a group.

Click a customer for their connections, flows and Recent activity: their latest runs with the time each started, and the details of any run you click. See all their runs in Flows · Activity opens every run of theirs, which you can narrow to Failed or download. Copy connect link is there too, and you can stop one flow for them.

In the API a customer is consumer_external_id, and every call names one with X-Ngentix-Consumer.

Related

What Settings is for

Settings holds your account, your organization and the plumbing behind the rest of the console, on five tabs.

The tabs

  • Account — your name, password, authenticator and sign-in. Appearance (Dark, Light or System) applies to this browser only.
  • Workspace — your organization's name, where we email you, and your team: Send invitation to add a teammate.
  • Public pages — Your subscribe page and its link (Copy link), and your Connector directory.
  • API keys — keys your own code uses to call Ngentix. See What API keys are for.
  • Advanced — the engine, your environment, Webhooks and Triggers. A webhook endpoint can't be removed from the console yet. Triggers are created through the API and can be deleted here.

Related

Concepts

How Ngentix fits together

Ngentix moves your customers' data between the systems they use and your product. Five pieces make that work; you set up three, your customers do two.

How Ngentix fits between your customer and your product One orange line, a flow of contacts every hour, runs from your customer's HubSpot through Ngentix into your product. Your customer connects their own HubSpot with their own sign-in or key, and subscribes on your page and pays per flow. You set up your product once. Flow · contacts, every hour Hs HubSpot Ngentix Ac Your product you set it up once their own sign-in or key Your customer subscribes on your page and pays per flow

What you set up

  • Your product — your own system, set up once under Connectors → Your product connectors.
  • Connectors — the systems you support, such as HubSpot or QuickBooks. Some need an app you register with the provider.
  • Flows — one kind of record moving between one system and your product, on a schedule. Customers subscribe to flows.

What your customers do

  • Subscribe — on your subscribe page they pick the flows they want, create a small account and pay per flow. Ngentix bills them; you pay nothing.
  • Connect — they sign in to each system, or paste its key. That connection is theirs: their sign-in, stored by us, and nothing else.

You are the organization. Your customers are the businesses that use your product.

Related

What each status means

Every screen uses the same words for the same thing. This page lists them.

Interrupted

Data stopped moving for a customer, and nobody chose it. The reason sits beside the word, for example Interrupted · Alder Freight: token expired.

You see it on the Flows list (1 of 9 customers interrupted), at the top of a flow's page (Interrupted for 1 customer), in the flow's Customers tab, and on the customer's own page.

It isn't always yours to fix. Often only the customer can sign in again; sometimes the provider is down. The reason, and Home's card for it, say who acts. See Fix an interrupted customer.

Removed by customer · Removed by you · Removed

Somebody chose to switch a connection off. The word says who:

  • Removed by customer — the customer disconnected it, on their connect page or in your app's connect button.
  • Removed by you — someone in your organization disconnected it here, or your server did with your secret key.
  • Removed — it was removed before Ngentix recorded who did it. We don't guess.

A removal is a choice, not a fault: it is never Interrupted, it isn't on Home's Needs you, and nobody is emailed to reconnect. If the removal cancelled the customer's paid subscription, they get one email confirming it (no further charges, when their paid period ends, no partial refund). Your server can hear it as the connection.removed webhook, which says who removed it.

Disconnecting inside the provider's own site (for example, removing the app in QuickBooks) reaches us as a failed sign-in, so it reads Interrupted.

On a flow it reads like 2 running · 1 removed by customer.

A flow's state

The first word in the Status column on Flows.

  • running — on, and running for its customers.
  • paused — you paused it; it says when it resumes.
  • off — not running, and nobody is charged.
  • withdrawn — you stopped offering it; customers who already pay keep it until their period ends.
  • halted — Ngentix stopped it for everyone, for safety. The page says why and how to lift it.
  • can't activate — something it needs isn't set up yet, for example needs Salesforce connected.

How a running flow is doing

Beside running, and at the top of the flow's page.

  • healthy — every customer's last run delivered.
  • Interrupted — data stopped for one or more customers (above).
  • Retrying — running, the last attempt failed, and it is trying again by itself. Nothing to do unless it lasts.
  • partial — one of several destinations isn't receiving.
  • missing a field / missing a required field — records arrived, but a field you mapped inside them didn't.
  • preparing — a customer's setup is still finishing.
  • Not run yet, Ready, Re-test — nobody has connected yet. Ready means you tested it; Re-test means that test is more than 90 days old.

A run's result

On a flow's Runs tab and in Activity, per run.

  • Worked — it ran and delivered what was new.
  • Failed — it stopped on an error; the reason is beside it. It retries by itself when the cause is temporary.
  • Did not start — nothing was sent, for example because the customer isn't connected.
  • Continuing — the other system asked us to slow down (a rate limit). The run delivered what it could, 19 so far, and the flow carries on by itself when that system allows, continues by 13:16. Nothing is lost and nothing is sent twice. It is never a failure and needs nothing from you: a rate limit is usually shared with every other app on the customer's account. If one lasts over an hour, Ngentix's own team is told.

One customer's flow

On a customer's page, per flow.

  • running — moving their data.
  • Interrupted — it worked and stopped; the reason is beside it.
  • removed by customer / removed by you / removed — the connection it needs was switched off on purpose, with the date (above).
  • can't run — they never connected the system it needs, so it has never run. Send them a connect link.
  • setting up — their connection is still being prepared.

Home and the map

  • Needs You — Home's list of things to look at, worst first. It's a list, not a status.
  • Interrupted — the same word on the map: data has stopped on this line for at least one customer.
  • Attention — worth a look, but data is still moving.
  • Idle — nothing moved for a week.

On Customers, people are grouped under Data has stopped, Data is moving with losses, or Nothing to do.

Related

Test with made-up data

You can build and try a flow without a real account at any provider. Three practice systems, marked synthetic data, return made-up but realistic records.

How to use them

  1. Open Connectors and find Sandbox CRM, Sandbox HRIS or Sandbox Support. Each is marked (synthetic data).
  2. Build a flow with one of them, as you would with any system. There is no app to register and no account to create.

Every record these systems send is invented.

Nothing on these systems is ever billed, to you or to your customers.

One environment

Your organization has one environment. There is no separate test mode and no separate test key: the practice systems are how you test. Settings → Advanced → Environments shows it.

Related

Why API keys and your provider apps live in different places

They look alike, but they protect different things, so they live apart.

An API key and a provider app are different things Two paths into Ngentix. Top: your server calls Ngentix with your API key, which is yours alone. Bottom: your customer approves your app on HubSpot's approval screen, and HubSpot lets Ngentix in; your app is shared by every customer who connects HubSpot. Your server API key yours alone Ngentix HubSpot Allow your app? Hs Your app is shared by every customer who connects HubSpot

API keys — Settings → API keys

Yours alone. Your own server uses one to call Ngentix. If you only use the console, you may never need one. A leaked key exposes your account; revoke it and the others keep working.

Your app with a provider — Connectors → the system → Setup

Shared by your customers. Every customer who connects HubSpot approves the same app you registered there. If its client secret leaks, every connection made through it is exposed, so it is encrypted and never shown again.

Most systems need an app from you (OAuth app from you). For the rest (Customer-provided auth), your customers paste their own key and there is nothing to register.

Related

When to use a publishable key

For developers putting the connect button in their own product. A publishable key (cc_pub_…) is the only key that is safe in a web page. It can start a connection and read your catalogue, and that is all.

Which key goes where A wall separates two lanes. Browser, where anyone can read the code: a publishable key plus a consumer token reaches Ngentix and can only start a connection, nothing else. Your server, where only you can read it: the secret API key reaches Ngentix and can do everything, so it never goes in a page. Browser anyone can read it Publishable key + consumer token starts a connection, nothing else Your server only you can read it Secret API key everything never put it in a page

Your other keys (cc_live_…) are secret. Anything in a web page is visible to every visitor, so a secret key in browser code is leaked the moment it ships.

Using it

  1. Under Settings → API keys, press Issue publishable key. You have one; rotate it to replace it.
  2. Put it in the connect button's code: a flow's page shows the snippet under How customers connect this flow.
  3. On your server, mint a short-lived consumer token for the signed-in customer and pass it to the button. Without it, the key cannot act for anyone.

Rule of thumb: code in a browser gets the publishable key; code on your server gets a secret one.

Related

What "on behalf of" means

For developers calling the API. Every call you make is made for one of your customers, and you say which one with the X-Ngentix-Consumer header.

One header picks one customer's account Your server calls Ngentix with the header X-Ngentix-Consumer: acme-42. Ngentix picks Acme's stored HubSpot sign-in and reaches Acme's account. A fainter second row shows globex-7 reaching Globex's account instead. One id, one customer's account; without the header the call is refused. Your server X-Ngentix-Consumer: acme-42 Hs Acme’s account X-Ngentix-Consumer: globex-7 Hs Globex’s account One id picks one customer’s stored sign-in. Leave the header out and the call is refused.

The header is how we choose whose stored sign-in to use. The same request returns one customer's contacts or another's depending on it. Leave it out and the call is refused with 400 missing_consumer, rather than guessing and returning the wrong company's data.

That is why you never handle your customers' passwords: they approve once, the sign-in stays with us, and your server names them by their id.

Which id

  • Customers you create through the API have the id you chose (consumer_external_id).
  • Customers who sign up on your subscribe page get an id we create, which starts cc_. The console shows their email or account name instead.

From a browser, with a publishable key, the customer is proven with X-Ngentix-Consumer-Token, minted on your server. See When to use a publishable key.

Related

What "circuit open" means

A provider kept failing, so we stopped calling it for a short while. Your flows retry by themselves; you don't need to do anything unless it lasts.

Circuit open: we stopped calling for a while Ngentix, an open switch, then HubSpot. The line from Ngentix ends at the open switch and the line on to HubSpot is faint: after repeated failures we stop calling for a short while, so the call never left Ngentix. A clock: it retries by itself. Circuit open Ngentix Hs HubSpot After repeated failures we stop calling for a short while. The call never left Ngentix: HubSpot was not asked. It retries by itself

Circuit open means we did not call the provider at all. The call never left Ngentix, so it is not a problem with your data or your mapping.

If it lasts

Open Flows → Activity and choose Failed to see the runs it stopped and why. If the provider has an outage page, check it.

If you call the API yourself

The error is circuit_open, classed retryable_after_delay: retry later, not never. The response says how long to wait, in the Retry-After header when present, otherwise in the message. Retrying at once only lengthens the wait.

Related

Whose name your customers see

When a customer connects a system by signing in, the provider shows them an approval screen. It shows the name you gave your app on that provider's developer site.

The name on your customer's approval screen HubSpot's own approval screen reads: Acme Sync wants access to your HubSpot account. Acme Sync is the name you gave your app on HubSpot's developer site. To change it, rename your app there. Hs HubSpot Acme Sync wants access to your HubSpot account The name you gave your app on HubSpot’s developer site To change it, rename your app there.

Name your app what your customers know you as. To change it, rename the app on the provider's site, not here.

Things that change it

  • Replacing the secret of the same app changes nothing for your customers.
  • Moving to a different app means your customers approve again, because their sign-in belongs to the app that issued it.
  • Key systems such as Klaviyo have no approval screen: your customers paste their own key, so there is no name to see.

Related