This article covers configuration methods and data storage options, focusing on user-facing Presets and internal Persistent Data.
Data Storage
There are several places to store and use data that will be useful to your integration in iPaaS.com: integration-specific custom fields, system-specific presets, persistent data, and mapping collections. Each one will be useful in different scenarios and can help you avoid having to hard-code any values in your integration that might need to be changed later.
Integration version-specific custom fields: This is a place to store fields that will be universal to all users. For example, if your integration has an
AppIdthat it uses in the external system to identify your integration, which is common to all of your users, this would be the place to store it. The values for these fields will be set in the integrator portal and will not be visible or changeable by subscribers or MiSPs. This area is commonly used to store any additional fields used during the OAuth process as well. By convention, we always store the API URL as a preset, not a custom field, even if it is the same for all users. Please note that fields and field values are both version-specific.Presets: A preset is a system-specific field used for the configuration of your integration’s behavior. The values are set via the Subscriber portal by a subscriber or MiSP. Generally, things like API username/password or API key would be stored in a preset. Presets are available in dynamic formulas for mappings, so they can also be useful to store configurations that might be used in multiple mappings. For example, if you need to send a username as part of every update command, you could store the username you want to use as a preset.
When possible, use a field type that matches your data. For instance, if the preset is about supporting or not supporting a feature, use a Boolean field.
Please name these in a human-readable way:
DO: API URL
DO NOT: ApiUrl
Persistent Data: This refers to data maintained by the integration itself. This can be useful for things like long-running tokens or the date of the last polling transfer that will be reused across multiple data transfers. The values will be visible and editable to users via the subscriber portal (after they are initially set by the integration), though they are generally maintained by the integration. Persistent data values can be assigned an expiration date, which can be useful for auto-deleting tokens once they have expired. These values are the only ones that are directly editable via your integration.
Please name these in a human-readable way:
DO:
Last Date of Customer PollDO NOT:
LastDateOfCustomerPoll
Mapping Collections - You may not think of it as data storage, but a mapping collection is often used to store values that vary in different use cases (see above note about presets as well). For example, if you need to send a username with each API call, but that username varies based on what type of data you are sending, the best place to assign it would be in each individual mapping collection.
Interface
Presets should be used for any data that is customer-specific and will be edited by a user. Presets are normally named in Title Casing. Spaces and special characters are allowed.
Presets are available by name in dynamic formulas, but their names will be modified to conform to C variable naming standards. This includes removing any spaces or invalid characters. E.g., Max API Usage% would become MaxAPIUsage.
Each preset should have a corresponding read-only property in the Settings class. This will allow for easy and consistent variable access in your integration code. For example:
public string ApiUrl { get { return GetSetting("Api Url", required: true); } }Persistent Data should be used for any data that is customer-specific and will be edited by your integration code. Names should be in Title Casing. Spaces and special characters are allowed. Expiration dates can be provided to automatically remove expired persistent data values.
Supported Features
See Supported Features for in-depth information.