When building a Custom Connector, there can be situations where you wish to work with user-defined objects within a system so you can’t be sure of the structure and other details of that data at the point you’re creating the Connector Methods.
Some examples:
- Creating a Method that works with a file, but the structure of the file might vary from customer to customer, or even use-case to use-case.
- Creating a Method that will operate on a custom object, and that custom object will be defined at “integration build time”, rather than “Connector build time”.
Being able to add Custom Fields to the Methods of an installed Connector can resolve some of these situations, but that then locks the Method (as well as that whole instance of the Connector) to working with that one structure. You could add all the possible Custom Fields to cover more than one file or object structure to a single Method, but that can then be difficult to work.
To make things simpler, Cyclr enables you to create Method Categories that can be copied and then used to target a specific structure or object when building integrations.
You do this by defining a Method Category as a “Custom Object Method Category” with the Category Customization Enabled toggle, as described below.
Having installed an instance of that Connector, you’ll then able to copy the Method Category which is defined as a Custom Object Method Category as many times as you need, and customize each copy for different data structures.
Enabling Method Category Customization #
To enable a Method Category on your Custom Connector to be copied to work with custom objects – making it a “Custom Object Method Category”:
- From your Console, go to Connectors > Custom Connectors and select the Releases button for your Connector.
- Copy the current Live Release to create a new Draft Release, then select Edit to modify it.
- Go to the Methods tab.
- Expand the Method Category that you want to modify, and select Edit Category.
- In the popup, turn on the Category Customization Enabled toggle:
If you only need the ability to copy a Method Category – and all the Methods it contains – on an installed instance of your Connector so they can be manually customized for different structured data in your integrations, that’s the only change you need to make.
There are further features you can take advantage of when creating Method Categories that will operate on custom objects, which are:
- Retrieving a list of those objects to display to the user when they copy your Method Category so they can simply select which one to use.
- Automatically adding Custom Fields for a selected object’s structure to the Request and/or Response Bodies of the Methods in that Method Category.
Using Parameters in a Custom Object Method Category #
To give the user options where they can provide details of which object to use in a copy of a Method Category, you define Category Parameters on it using the Edit Category popup:
In the screenshot above, we’ve added a “MailingListID” Category Parameter.
When a user goes to an instance of that Connector and copies this Method Category, Cyclr will prompt them to provide a value for the MailingListID.
By also defining a Parameter Lookup Trigger that calls a Trigger named “Mailing List Lookup” (which executes another Method on our Connector to retrieve available Mailing Lists) we can have Cyclr display a dropdown of available Mailing Lists for the user to choose from.
In some situations, a single Parameter may be all that’s required, but others may need the user to provide multiple values. One example is when creating a Connector to work against a database system where you need to know the database to use as well as which table within that database.
There you would create 2 Parameters which might be called:
- Database
- Table
If that system’s API exposes endpoints you can call to retrieve a list of available databases, and available tables within each database, you can add Methods and Triggers to your Connector for them.
When calling the “table lookup”, the underlying Method would require the name of the database the user chose for the Database Parameter, which would be available as a system mergefield using this syntax:
{{CyclrObjectName_[Parameter Name]}}
For the “Database” Parameter, that would be {{CyclrObjectName_Database}}.
That mergefield could then be used within the Endpoint property of a Method you’ve defined as the “Parameter Lookup Trigger” for your Category Parameter:
Or within the lookup Method’s Request Body by setting it as the Default Value of a Field:
Enable field auto-discovery #
To have Cyclr automatically add Custom Fields to a Method in a Custom Object Method Category, go to the Request Format tab of any of the Methods within the Category and select a method from the Custom Fields Lookup Method dropdown:
The Method selected will have access to the Category’s Parameters using the {{CyclrObjectName_[Parameter Name]}} Mergefields as described previously.
See the article on Dynamic Custom Fields for more details on creating those Methods.
Using a Custom Object Method Category #
More information, including how users work with Custom Object Method Categories, is explained in this article: Custom Object Method Categories.
