Connecting Fergus with Formpiece
The Fergus credential is how Formpiece reads your Fergus calendar and creates customers, sites and jobs from bookings. The account has one, chosen under Fergus Bookings, then Settings, then Fergus Credentials, and every Fergus form uses it. The credential itself is made under Integrations.
Before you start
- Decide which way to connect. Simple logs in to Fergus. Advanced uses a Personal Access Token that you generate in Fergus and paste in. The choice is made once, when the credential is created.
- For Advanced, the dashboard's help says to go to Settings > Integration Centre > Fergus API in Fergus and click Generate new token. Fergus shows the token once, so copy it before leaving the page. Only the Account Owner, or a Full User with Master Admin access, can generate one.
Step by step
Connect with a login (Simple)
- Open Fergus Bookings, then Settings, then Fergus Credentials, and click Create Fergus credential. If the account already has one, the button is Create new Fergus credential.
- Leave Integration Mode on Simple - Login to Fergus to set up the integration.
- Click Log in to Fergus, then confirm the "Confirm Fergus login" box. You are sent to Fergus to log in and brought back to the same page.
- The page says "Fergus connection confirmed for" followed by the email you logged in as.
- Change the Name, which starts as "Fergus login integration", and click Save.
Connect with a token (Advanced)
- Click Create Fergus credential as above and choose Advanced - Generate a Personal Access Token and enter it manually.
- Give it a Name, paste the token into Fergus Personal Access Token, and click Save.
- Leave Token expires blank to use one year from today, or enter the date. Fergus tokens last a year.
- Click Test Connection to check it.
Choose it for the account
- Go back to Fergus Bookings, then Settings, then Fergus Credentials.
- Pick the credential under Fergus Credential.
- Click Update Fergus credential.
The change applies to every form straight away. Nothing needs republishing. A credential whose login has lapsed is listed with "(needs connecting again)" after its name.
What changes when you swap or clear it
The staff on a form, the team members on a service and the follow up user on a callback are kept as Fergus user ids, and an id means something in one Fergus account only. Changing to a different Fergus account leaves those ids pointing at the wrong people.
Before it saves, Formpiece asks "Change the Fergus credential?" and says how many forms book into the account. When it can see the two credentials belong to different Fergus users, it names both emails and says each form will need checking before it takes bookings again. Click Change credential to go ahead.
After a swap, open Service Calendars on each form. Staff who are not in the new Fergus account show "(no longer in Fergus)", a team member shows "No longer an active user in Fergus. Remove them, or no time can be booked.", and the form's setup checklist stops counting them (see Use the setup checklist). Choose staff again, and pick the callback follow up user again on any service that has one (see Callbacks).
You cannot clear the credential while the account has forms, archived ones included. Formpiece says "Cannot clear the credential" and asks you to choose another one or delete the forms first.
Deleting a credential from Integrations revokes the connection at Fergus and removes the saved token.
When it goes wrong
"The Fergus connection was revoked or has lapsed"
Formpiece marked the credential as needing to be connected again because Fergus refused it, or the login was revoked in Fergus. The Dashboard shows a Reconnect item and a Reconnect Fergus button, and no booking can be sent to Fergus until it is reconnected. For a Simple credential, open it from Integrations and click Reconnect Fergus. For Advanced, paste a new token into Fergus Personal Access Token and click Save. Bookings that came in meanwhile can be sent again from Bookings (see Bookings).
"This token expires in 12 days" or "This token has expired"
Nothing renews a Personal Access Token. The credential's page warns from 30 days before the Token expires date, and the Dashboard adds a Needs attention item and a Token expired status once it has passed. Generate a new token in Fergus, paste it into Fergus Personal Access Token, set Token expires, and click Save. Every form uses it straight away.
The date is the one you typed, or one year from the day you saved the credential. Formpiece uses it for the warnings. If you entered the wrong date the warnings are wrong, and a token Fergus has turned down is only noticed when a booking fails.
The saved token is never shown again. Leave the field blank to keep it.
"Could not connect to Fergus."
The message carries Fergus's reason. For Simple, log in again. For Advanced, check you pasted the whole token and that the user who generated it is still active in Fergus.
"Logging in with Fergus has not been set up yet. Use the Advanced mode with a Personal Access Token instead."
Simple login isn't available on this Formpiece installation. Create the credential with Advanced.
"Fergus is not available yet"
Fergus is not enabled on this account, so there is nothing to create a credential against.
Status shows "Not confirmed"
A credential is chosen, but Formpiece hasn't had Fergus confirm that it works. Use Test Fergus credentials (Simple) or Test Connection (Advanced) on the credential.
"The Fergus credential is already set to this one."
You clicked Update Fergus credential without changing the selection.
FAQ
Can one form book into a different Fergus account?
No. The credential is set once for the account and every form uses it.
Do I need to change my forms after replacing a token with one from the same user?
No. Paste the new token into the existing credential and every form picks it up.