Settings #
This tab is where you setup the general operation of a Method:
| Property | Description | Standards |
|---|---|---|
| Name | The name of the method to appear in the Cyclr UI for the user to see. | Should be short and snappy and have initial caps for nouns/verbs, lowercase for minor words (like “a” or “to”), e.g. “Delete Emails”, “Get All Contacts”, “Send to List”. See below for suggested naming conventions. |
| Description | This is the description of the method to appear in the Cyclr UI for the user to understand what the method does and be informed of any special/interesting values to pass. | Can be quite lengthy if appropriate. Can also include links to helpful API documentation if useful. |
| Warning | ||
| Status | ||
| Comments | ||
| Category | Used to group methods in the Cyclr UI. | Try to keep simple and pluralized, e.g. “Contacts” or “Mailing Lists“. |
| Subcategory | ||
| Method Type | This defines how a Method will function. Options: * Action * Webhook * WebhookResponse * Script | |
| HTTP Method | Only available if Method Type is set to “Action”. Sets the type of HTTP Request which is used. Supported HTTP methods are: * GET * POST * PATCH * PUT * DELETE | |
| Endpoint | Only available if Method Type is set to “Action”. This is the URI that will be sent a request when the Method is executed. | |
| Hide | Whether the Method should be hidden or visible within Cyclr’s interface. | |
| DataType | This is the data type used for the request or response body, according to the external system being called. Read more about Data Types for Request and Response Formats. | |
| Xml Root Element | If using XML, this is the root element for the XML document. | |
| Ignore Authentication? | Whether the Method should prevent the Connector’s authentication values/HTTP Headers from being included in its Requests. Useful when a Method is built to send Requests to an endpoint which is publicly accessible so doesn’t require any authentication to be provided. Some APIs return an error if the standard authentication details set at the Connector-level are included in those Requests. |
Some suggested Connector Method naming conventions which we use in our Library Connectors:
| Name | Purpose |
|---|---|
| Get [ObjectNameSingular] | Used when the method retrieves a single object. Example: “Get Contact” |
| List [ObjectNamePlural] | Used when the method retrieves multiple objects. Example: “List Contacts” |
| Create [ObjectNameSingular] | Used when the method creates an object. Example: “Create Contact” |
| Create [ObjectNamePlural] | Used when the method creates multiple objects from a single call. Example: “Create Contacts” |
| Delete [ObjectNameSingular] | Used when the method deletes an object. Example: “Delete Contact” |
| Update [ObjectNameSingular] | Used when the method updates an object. Example: “Update Contact” |
Rate Limits #
You can specify any Rate Limits that apply to this Method, to restrict how quickly Cyclr can make calls to the Method when running Cycles that use it.
For more detailed information of what’s possible and how Rate Limits set at both the Connector-level and Method-level work together, see this Rate Limits article.
Request Format / Response Format #
These 2 tabs allow you to specify the Request and the Response formats according to the API endpoint the Method is implementing.
You define any Fields Cyclr should use for both, as well as other configuration options that affect how the Request Cyclr builds is structured, and how the Response it recevies when making a call is handled.
Fields #
Note: if you use the Generate Fields button on this tab to generate the Fields from a sample payload, you must first to set the Format’s Data Type (e.g. to JSON, XML, etc) so Cyclr knows how to interpret the data.
| Property | Description | Standards |
|---|---|---|
| Connector Field | The name of the field as used by the remote application’s API. Use Cyclr notation to locate the value, e.g. [records].EmailAddress when receiving an array and retrieving the EmailAddress attribute from an element within that array. | |
| System Field | The name to use internally within Cyclr. Use the field as capitalized by the API and remove any spaces. Apps that have the same SystemField name can auto match values in the builder, saving time and making life easier. | |
| Display Name | The name of the field to be displayed in the Cyclr UI to the user. | |
| Description | This is the description of the Field to appear in the Cyclr UI for the user to understand how the Field is used. | Always include this and keep fairly short (no more than 100 characters). |
| Hidden | Request Format only. Whether the Field should be hidden from the Cyclr interface. | |
| Optional | Request Format only. Set to true if the Field doesn’t have to be given a value. Leave out if it’s a required Field. | |
| Data Type | Used to set the type of data a Field will contain. Cyclr will also use this Data Type when converting data to/from the Field. Read more about Data Types and Fields. | |
| Default Value | ||
| Trigger | Request Format only. Used to define a Method to use to retrieve a list of possible values the user can choose from when setting a Field Mapping for this Field. | |
| Part | Request Format only, and only used when its Data Type is set to MultipartFormBoundaryDefined. Indicates the body part of the Request Format a Field relates to. |
Custom Fields Lookup Method #
Enables Cyclr to automatically retrieve the structure of the Request or Response data from the remote API, to create Fields in the Request or the Response from.
More on this can be found on the Dynamic Custom Fields page.
Time Filter Field #
Only found on the Response Format tab.
Some APIs provide endpoints that return only “new” or “changed” data by having a date/time parameter you can pass to them, allowing you to create “List New” and “List Updated” Methods. The date/time value to pass in would be Cyclr’s Last Successful Run Date value to get data that’s new or changed since the last time a Cycle Step ran.
If the API doesn’t provide those endpoints, you can instead use an endpoint that returns all of the data, and have Cyclr filter out any items that were either created or updated (depending on your use-case) since the last time a Step ran.
For this to be possible, the the API must include a property such as “lastModifiedDate” or “createdTimestamp” so that Cyclr can filter it. If you set the property as the Time Filter Field, Cyclr will automatically remove any items it gets back that are before the Cycle Step’s Last Successful Run Date.
Is ZIP file returned? #
Only found on the Response Format tab.
Enabing this option tells Cyclr that the Response data will contain a compressed file so should be decompressed to obtain its actual contents.
Cyclr supports the following file formats:
- zip
- gzip
Parameters #
You can specify Parameters specific to this method. Read more about parameters
Script #
You can add script to the connector to handle special situations. Read more about scripting
Script Method Type
The “Script” method type can be used for methods that do not make an external API call (e.g. static data), or where requests will need to be handled entirely by the script engine.
Note: Methods using the “Script” Type only count towards your Monthly Task Usage if they use the http_request() function.
Mergefields #
Mergefields are placeholders that will be substituted at runtime.
- LastSuccessfulRunDate – is the last time a Step successfully ran. This is useful to find newly created or updated records in an app. A format string needs to be provided. For example, {{LastSuccessfulRunDate format=yyyy-MM-ddTHH:mm:ssZ}}.