V 1.0.0
OVERVIEW
Understand and review these best practices for developing connectors.
GOALS
Understand best practices for building connector authentication, parameters, inputs, and outputs.
Review using version control inside of the connector builder.
Review logging techniques to troubleshoot and identify what is happening with connector errors.
Review best practices for building test Flows.
Review Definition of Done (DoD) checklist.
Authentication, Parameters, Inputs, and Outputs
Authentication
A connector will always require some form of authentication. The link to the complete auth documentation can be found here.
We recommend using an existing form of authentication such as Basic, Oauth1, Oauth2, etc. However, our platform does allow for a custom form of authentication, where you can define exactly how you’d like the connector to authenticate for every request.
A useful practice for troubleshooting and/or identifying how the authentication workflow works is to use a external tool such as Postman or cURL to get visibility into the traffic, and verify that the authentication works as expected.
Parameters
Parameters are an optional form of input for Events and Actions. Complete documentation can be found here.
In general, if your parameters have API support for that service, then it will be a good idea to dynamically generate them, as opposed to statically generated values (i.e. hard coded).
There are two forms of parameters - text input (strings), or dropdown fields.
For parameters about Search related cards, always provide two options for the user to choose from: return first matching record or all matching records. A good example is:
{
"result": {
"type": "option",
"displayname": "Result",
"choices": [
"First matching row",
"All matching rows"
]
}
}Inputs
Complete documentation can be found here.
In general, if there is API available for dynamically generating input fields, it’s a good practice to dynamically generating them, as opposed to statically generated values (i.e. hard coded)
Input field name should be self-explanatory and clear, with the first letter capital and spaces between words, like “Fixed Cost”, not “FixedCost” or “fixed cost”.
If an input field is required for performing a request, you can set the field to be required. An example of making an input field as required is:
{
"name": "Quantity",
"type": "number",
"required": true
} Some APIs have a default value for a non-required field in case user didn’t fill the field. An example of adding a default value for an input field is:
{
"name": "FixedCost",
"type": "number",
"defaultValue": 0
}Outputs
Complete documentation can be found here.
In general, if there is API available for dynamically generating output fields, it’s a good practice to dynamically generating them, as opposed to statically generated values (i.e. hard coded)
The same as Input field, Output field name should be self-explanatory and clear, with the first letter capital and spaces between words, like “Fixed Cost”, not “FixedCost” or “fixed cost”.
If the output is a collection of records with the same type, using the “collection” flag. An example is:
{
"name": "Rows",
"type": "object",
"collection": true
}Internal Documentation
Connector Metadata
Platform development tracing is currently a feature undergoing development. In the meantime, we require that we add the following info as top level keys to the connector. Tip: In your workspace, you can press the “Export” button at the top-right to get the full connector code in an easy-to-copy format.
{
"original-author-email": "email",
"last-changed-by-email": "email",
"change-log": "date/description1,date/description2,...",
"api-support-contact-email": "email1,email2,...",
"api-version-supported": "1.0",
"software-version-supported": "softwareversion1,softwareversion2,.."
// connector code
}Version Control
Connector Versioning
Connector builder has a basic form of versioning, that uses a standard semantic versioning pattern. Connector versions have three digits, all separated by a period. E.g. 1.0.5. Check this link for reference.
It is recommended that you save new versions of your connector periodically - especially after a day of work. It can be easily overwritten if not saved to a new version, because otherwise it is possible that you or another developer can overwrite your existing DRAFT of your code.
Best practice is for the following:
Increment major version when:
- Updates to the connector are not backwards compatible/breaking changes.
Increment minor version when:
- New features added that are visible to the end user.
Increment patch version when:
- Bug fixes, any changes that are not visible changes to the user, and do not break any backward compatibility.
Important: When making new changes to a connector, it is important to always start with the currently deployed version, and work off of that. The live version of a connector can be found in designer by choosing any action or event for that connector, clicking the gear cog icon in the bottom right, click ‘Edit Card’, then click on the card Title. A modal window should open - click the ‘+ More’ button, which will then surface a method address field that includes the connector version.
Logging
Logging Your Connector Data
Connector execution tracing is currently a feature request in development. For now, we must build tracing into the connector executions ourselves.
The most effective method is to write the data to some API. A useful tool is using our Webhook monitors (API Endpoint) as the ingestion point for your data.
Once you have chosen your data logging source, then you will want to write functions that log to that source. It would be a good idea to write this functionality such that it is reusable across all actions and events. Then you can call this function in each connector. This allows you to capture usage and/or error data for your connector.
We recommend that you use an API endpoint Flow, that log to our proprietary tables. It will be up to the developer to choose what and how much data to save to the table.
Test Flows
What are Connector Test Flows?
Test Flows are created in designer to assure that a connector performs as expected from the customers perspective. The health status of each connector is tracked by capturing errors thrown during regular testing intervals.
Whenever a new action or event is developed, it needs an associated test Flow that tracks the health status of the connector. These Flows shall be set up to call an error handling Flow that communicates any Flow errors to a master Google Sheet for tracking individual action/method health.
Definition of Done (DoD)
Checklist
_authping function
authpingErrorHandler function
Custom API Action
- Function that generates input fields for Custom API Action.
Unit test for the Custom API Action
Help Documentation
Authentication
- Ensure that we provide the info for the relative URL syntax.
Events & Actions
Markdown: file naming convention
Required header fields:
title (display title of connector)
type (connector-action/connector-event/connector-authorization)
date (must be set in present or past to appear in designer)