In Cyclr, integration Templates are reusable integration workflows that you can design and build in your Partner Console. A template can be deployed repeatedly on multiple Accounts, saving you time from rebuilding integrations from scratch each time.
Connectors allow you to integrate with third-party services, such as CRM and marketing tools or accounting systems. However, before these connectors can function, they need to be installed and authenticated.
In this lesson we take a look at how to install templates and connectors into Accounts, and how to handle connector authentication with authentication tokens.
Deploying Integration Templates
There are multiple ways you can choose to deploy and offer integration templates to your end-users depending on your use case. You can choose to install them directly into a customer’s account (either from the console or programmatically using the Cyclr API), or allow your users to install them from a marketplace.
When you install a template into an account, Cyclr will also install all the connectors that the template needs to run to the account.
From the Partner Console
If you prefer to maintain control over complex workflows or provide a higher level of service, you can manually install templates for your users’ Accounts. This option lets you configure the integration for them, giving you the chance to ensure everything is set up to your specifications before making it available.
Here is how you can introduce a template into an account manually:
- Navigate to Account Management, and access your desired account from the “Open Account” button. This will take you to “Cycles” view, showing you a list of cycles that are currently on the account.
- In the top right, you can find a selection of buttons. Click on the one that reads “Templates”.
- You will be presented with a list of all your published templates. Select the one you want to install by clicking the “Use Template” button.
- This will create an exact copy of the template you chose as a cycle on the account, and present it to you in the builder. Here you can tweak the cycle as needed to fit your customer’s specific requirements.
Via the API
You can also install templates onto an Account programmatically via our API. This requires you to make a POST call to the POST /v1.0/templates/{Template ID}/install endpoint.
The request should look like this:
POST /v1.0/templates/{Template ID}/install
Authorization: Bearer ****************************************************************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000Here, Template ID represents the ID of the template you are installing, and the X-Cyclr-Account should hold the API ID of the account you want to install the template to.
An example response is available in our Install a Template documentation.
Through Marketplaces
Cyclr supports a self-service model, which enables your end-users to browse and install Integration Templates from an embedded marketplace. We’ve already discussed the different deployment methods that are available.
Once you have deployed your marketplace, your customers will be able to access your marketplace, where they can pick and choose the templates that you have made available for them. When they select to install one, the template will be introduced as a cycle to the customer’s Account, along with it’s applicable connectors.
Exporting and Importing Cycles between Accounts
Exporting and importing cycles between Accounts is another way that you can install new integration to an Account. It saves you time and effort in building your workflows, as it allows you to reuse integrations that you’ve already built for one customer with another Account. It also comes in handy if you have Consoles on multiple Cyclr instances, but you can read more on that in our documentation.
Export Cycles
To export a template or cycle, you first need to find it either in your Template Library or in the cycles area of the account. In the array of buttons next to each cycle, you will find the “Export” button. For templates, you need to first navigate to Template Releases and then choose the release version you want to export.
This will download the template as a JSON file onto your machine. It’s important to note that Account connector properties, webhook key mappings and cycle linking steps are not currently supported in Export/Import. It’s also good practice to ensure connectors and step methods used in the exported template or cycle are on the latest version.
Import Cycles
To import a template or cycle to an account, you first need to navigate to the Account where you want to import it. You will find an “Import Cycle” button at the top right corner of the Cycles area.
You can then choose to import your template or cycle by either choosing and uploading the full JSON file from your computer, or by pasting the full JSON into the appropriate field. Finish the import by clicking the “Import” button, which will introduce the file as a new cycle to the account.
Installing Connectors
Apart from installing connectors alongside templates, you can add connectors into Accounts also individually, to make a selection of connectors available for the Account.
Note that when you install connectors to an account this way, that connector instance remains private and can only be accessed by that Account and it’s sub-accounts. This allows you to make small changes that are specific to that Account, should you want to give the connector a specific name or description that is only relevant to that customer alone.
Here is how you can go about installing connectors to Accounts independently from templates.
- Navigate to the Account through Account Management and open the account.
- Go to the Connectors area, and choose “Install New Utility” or “Install New Application”, depending on the type of connector you want to install. You can read more about Utility Connectors and Application Connectors from our documentation.
- You will be presented with our Connector Library. Search for the Connector you want and click on Install to go through the installation process. This can vary depending on the connector, but you can find the setup guides for all application connector from our Connector Guides.
The installed connector will now be available on that account, ready to be used in integration cycles.
You can also install templates onto an Account programmatically via our API by calling the /v1.0/connectors/{id}/install endpoint.
Authenticating Account Connectors
Authentication ensures that Cyclr can access and interact with the customer’s data securely.
With Cyclr, you can handle authentication with your customers safely, whether or not you provide them Access to Cyclr directly. If your customers have access to their Accounts, they can naturally authenticate their connectors easily through Cyclr’s interface on their own.
But even in the instance where you don’t want to give your customers their own access to Cyclr, you can still manage authentication safely with Connector Authentication Links.
Generating an authentication token
With Cyclr, your customers won’t have to share credentials with you, nor do you have to go through awkward authentication calls with them. Instead, you can generate an authentication link and token that you can send to your customer via email.
Here is how you can send an authentication token to a customer:
- Navigate to Accounts and Account Management in your Partner Console, and find the Account that holds the Connector that requires authentication.
- Access the Account from the Open Account button.
- Once you are in the Account, navigate to Connectors, and find the Connector that you want the client to authenticate. Click on the Edit Connector button.
- At the top of the page, click on the Generate Set up Token button.
- Select the user who you’re generating the token for, and pick an expiry date and time for the link. If you don’t set a specific expiration date and time, the token will expire after 5 minutes by default.
Cyclr will then generate a single-use sign-in token and link to a web page where your customer can enter it. This way they can authenticate the connector with their details without passing their credentials to you.
Once your end-user has entered their token into the web page, they have 12 hours to authenticate the connector, giving them plenty of time to go through the authentication process when it’s most convenient for them. However, the token can only be used once, so if they start the process but don’t complete the authentication, you will need to generate a new token and link for them.
Key Takeaways
- You can deploy integration templates on Accounts either manually, via the API, or by allowing your customers to self-serve via Marketplaces.
- Installing a template will also add it’s required connectors into an Account.
- You can manage authentication with your customers easily and safely with an authentication link and token.