Setting up parameters in your connector requires you to go to the Parameters tab either on the Connector level (for Connector level parameters) or on the Method level (for Method level parameters).
Do keep in mind that any parameters set at the Connector level can be used by all Methods, whilst Method level parameters are only applicable to that Method. It’s good practice to set anything that you know happens on every method as parameters on the Connector level, but you would not do this if even one of your methods doesn’t use that parameter.
To add Parameters, in the Parameter tab, click on the ‘Add Parameter’ button and provide a name that is identical to the object that it will use. This will create a parameter with some preselected property values that you can change to what you need from the little pen icon next to each field.
You will be asked to provide the following information:
| Property | Description |
|---|---|
| TargetType | Select here the parameter type. HttpHeader, MergeField, QueryString, FilterField, ResponseField, Script |
| TargetName | Set a name for the parameter. This should be in PascalCase and identical to the object you want to use for it. This is important, as even the slightest mismatch will cause issues. |
| DisplayName | Set a display name for the parameter that will be visible to users if the parameter is not hidden. Cyclr will automatically extrapolate a display name from the target name, but you can change this as needed. |
| Description | Description for what the parameter is used for. |
| Trigger | Trigger name for the parameter. If you want to dynamically show a list of parameter values for the user to choose from, set here the name of the trigger you want Cyclr to call. Please see the Triggers lesson for details. |
| Hidden | Here you can determine if the parameter is visible for users. You can use this to hide internal parameters that you don’t want users to see. Defaults as false. |
| Optional | Set the parameter to be optional or required. Defaults as true. |
Connector level Parameters have these additional properties:
| Property | Description |
|---|---|
| Sensitive | The Parameter is treated as a password by masking the value in the interface. Use for sensitive values. |
| Property Type | Can be set as “Account” or “Partner”. An Account Connector Property parameter is shown to the user when installing or setting up the Connector, whilst a Partner Connector Property parameter is available in the Cyclr Console’s Application Connector Library entry and can be set once for use across all Account Connectors. |
| Multiline | The Parameter is displayed as a textbox allowing multiple lines to be entered, rather than a single line textbox. |
In this lesson we will cover how to set up and use the most common Parameter Types in Cyclr: HttpHeaders, MergeFields, QueryStrings and ResponseFields.
MergeField
A MergeField parameter is used to insert data within an EndPoint. It acts as a placeholder in the method endpoint, which gets replaced with data before the request is made, allowing you to call upon a certain object to pinpoint the request.
The MergeField is identified by the double opening and closing curly braces, {{}}. When a user specifies some data, or passes data from a previous step into a MergeField, the {{}} are replaced with the data before the request is made.
To create a MergeField within Cyclr, in the Parameters Tab, Click ‘Add Parameter’ and name it identically to the object you want to use for it. From the ‘Target Type’ setting, select ‘MergeField’, and complete the properties as needed.
MergeField Use Example
For a Method level example, we are setting a MergeField on a GET Contact method. The MergeField represents a Contact ID, as it’s an identifiable piece of data that is common but distinguishable in all Contacts.
We name the MergeField according to how a Contact Id will be presented in the response, ContactId (in PascalCase) . We also will be setting it as non-optional because you need an ID to ‘Get’ a contact.
Like this:
Once the MergeField is created, we need to tell the Connector where it can be used. In this example, we would go to the Method’s Settings tab, and add our MergeField’s name in curly braces at the end of the domain, {{ContactId}}. This will add the desired Contact’s ID to the request call and let’s us get the data for that that Contact in the response.
HttpHeader
HttpHeader parameters, as the name suggests, will be added to the HTTP header of the Request. They are a separate part of the request from the Request Body and the Request EndPoint. Headers are typically used with Authentication-related tasks.
To add a header to an API request in Cyclr, create a new parameter (either at Connector or method level) with Target Type set to ‘HttpHeader’. The Target Name of the parameter sets the header key in the API request.
QueryString
A query string is a parameter which is attached to the end of a request URL as a key=value pair after a question mark. It allows you to add values into the QueryString of an HTTP request, and is especially useful when you want to add optional filtering criteria to the request call.
Note that Cyclr cannot determine which parameters are available on the endpoint. While you can add as many query string parameters as needed, their functionality depends on the implementation of the API endpoint.
In the example below, you can find the query string in bold.
example.com/search**?name=value**If you have multiple query strings, they are separated with an ‘&’.
example.com/search?name=value**&type=value**Query strings are often used when data is not required in a specific order. You can generally (but not always) send query strings in whatever order you wish. For example, both of these examples are likely to be valid:
example.com/search?name=value&type=valueexample.com/search?type=value&name=valueThis differs from a MergeField in that a Mergefield will always place data in exactly the same place in the End Point.
example.com/{{LocationId}}/{{ContactId}}In the above example, the Contact Id will always follow the Location Id, because MergeFields are fixed within the EndPoint.
To add a query string in Cyclr, create a new parameter and ensure the parameter type is set to Query String. The target name of the query string will be the key name of the query string, and exactly how it appears after the URL.
Response fields
You may remember Response Fields from the Methods lesson, so it might seem unusual to see ResponseField as an option within the Parameters tab. However, a ‘ResponseField’ parameter acts very differently to a Response Field in the ‘Response Format’ tab.
A “ResponseField” type parameter will automatically store a value from a response body to use in the next request. This is particularly useful in Paging, which will be covered in more detail the Paging lesson.