Introduction #
When creating a Template, you’ll often be working with “known objects” – objects that are always present – such as Leads or Contacts within a CRM system, or Mailing Lists within an Email Marketing system. The Cyclr Connector you use to work with that system will likely have Methods that act on those particular objects, such as List Contacts or Update Lead. In these situations, you can build a Template that’s ready to go and doesn’t require much additional configuration.
The fields that exist on those objects may differ from one customer’s CRM account to the next if they’re able to add “custom fields” within that CRM system, but the underlying objects are common across all of them so Methods can be created specifically to work with them.
Custom fields don’t present a problem as Cyclr is able to retrieve custom fields if a system’s API exposes ways to retrieve them, and when that’s implemented on a Connector using Dynamic Custom Fields (whether for a Library Connector or one of your own Custom Connectors), Cyclr will automatically add those custom fields to the existing Connector Methods.
In some situations however, you may be working with a system that allows the customer to create whole custom objects of their own. Salesforce is one such system. In those cases, there won’t be Methods that are immediately “ready to go” to work with those objects.
This doesn’t prevent you from creating Templates though, as Connectors in Cyclr can implement “Custom Object Method Categories” which allow creation of a group of Methods under a single Method Category that can be configured to work with a specific custom object that’s discovered at the point a Template is installed.
This makes it possible to create a Template without knowing exactly what the objects – as well as their fields – are that will be used after it’s been installed.
You can therefore build a Template using “placeholder Steps” where the unknown objects will be used.
When the Template is installed (whether manually using the “Templates” button within a Cyclr Account, or through the LAUNCH and Marketplaces features), the user installing it provides details of the custom object. That creates a new Method Category for it automatically as part of the installation, and the placeholder Steps are replaced by instances of the Methods created for that new Category.
This feature is configured on some Library Connectors and can also be setup when building your own Custom Connectors, as described here.
Identifying Custom Object Method Categories #
You can identify a Method Category on an installed Connector as being a “Custom Object Method Category” by going to its Edit Connector/Settings page and expanding the Categories.
The “Copy” button is shown for any Categories that can be duplicated to work with custom objects, as shown for the “Enhanced Objects” Method Category on the Salesforce Connector shown in this screenshot:
Also, when in the Builder, if you attempt to drag in a Method from the original Custom Object Method Category, a notification will be displayed in the bottom left, indicating that Method may require additional setup before it can be used, which could simply be copying the Method Category, or may be copying it and providing one or more parameters.
Using a Custom Object Method Category #
This walkthrough demonstrates working with an authenticated Salesforce Connector and the “Enhanced Objects” Method Category in a Template.
1. When building a Template, you first create a copy of the Method Category you wish to use with the “Copy” button:
2. You’ll then see the “Copy Category for Custom Object” popup:
This particular Category has been setup on our Salesforce Library Connector to retrieve a list of objects found within the Salesforce account the Connector has been authenticated against, and these are shown in the Object dropdown:
Note: If a Category on a Connector hasn’t been setup in this way – or the object isn’t shown – you can manually enter its name as it appears within that system using the Object Name field.
3. Select “Copy” and a new Method Category will be created on that Connector for the new object. It will have a small icon next to it which identifies it as a Custom Object Method Category, as shown by the new “Account” Category here:
Additionally, because the Methods within the Salesforce Connector’s original “Enhanced Objects” Category have been configured to use a “Custom Fields Lookup Method“, Cyclr automatically retrieves the fields for the “Account” object that was chosen and creates Custom Fields on the Methods.
4. Back in the Builder, the “Account” Category is shown under the Salesforce Connector and can be opened and its Methods dragged onto the canvas as normal:
Once placed on the Builder’s canvas, Steps using Methods from Custom Object Method Categories also display that same icon so you can identify them:
Installing a Template #
When installing a Template containing a Step that uses a Method from a Custom Object Method Category, the default behaviour is for the object specified in the Template to be used in the newly created Cycle – so the usual process happens where the Template is simply copied into the Cyclr Account to create a new Cycle.
That may be correct if the object you specified when building your Template is what should be used when installed into the customer’s Cyclr Account, or if the object is identified in exactly the same way for you as it is for them (e.g. an object called “Account” in one customer’s system will also be called “Account” in another).
That won’t be correct if creating an “Account” object in each customer’s external system would result in a different identifier being used, such as with systems that use integer values or Globally Unique Identifiers (GUIDs/UUIDs) to identify their object types, rather than simple text values.
In those cases, you just need to enable the “User Configurable Category” option found in the Builder by clicking the Step’s “Step Setup” button, then opening the Advanced Settings area and toggling the option:
With this option enabled, when the Template is installed, the user installing it will be prompted to specify the object to be used.
That happens when the Template is installed using any of these routes:
- A Console User or an Account User within a Cyclr Account uses the “Templates” button to select a Template.
- Using Cyclr’s LAUNCH feature.
- Using Cyclr’s Marketplaces feature.
Example when installed from a Cyclr Account’s “Templates” button:
Example when installed using LAUNCH or a Marketplace:
