Overview
The Catsy integration provides a set of ready-made functions you can call when building mappings. They handle common lookups and conversions between your iPaaS.com data and Catsy, such as resolving category IDs, ensuring product tags exist, and reading a value from a record's additional properties, so you do not have to write that logic yourself in a formula.
Where you can use these functions
These functions are available anywhere you write a formula for the Catsy integration:
Dynamic Formula mappings: where a destination field's value is produced by a formula rather than mapped directly from a source field.
Mapping collection filters: where a formula decides whether a record should be processed.
Error filters: a mapping collection's error filter, which sits alongside its collection filter. When the error filter's formula resolves to true, the transfer raises an error that is held in the Error Logs for review and is not retried automatically.
Translation collections: where a translation entry uses a formula as its source value.
How to use them
Call a function by name and pass the values it needs in parentheses, for example:
await GetCategories(SourceCategories).Each function's signature shows its name, the parameters it accepts (with their types), and the type of value it returns. Use it as the reference for exactly how to call the function.
Function names and formula syntax are case-sensitive, so type each name exactly as shown. Whether the values a function matches are treated as case-sensitive varies by function, and is called out in the relevant parameter's description.
Some of these functions are asynchronous (their signature returns a
Task) and must be called withawait; the rest are synchronous and are called directly. Each function's How to call it example shows the correct form.Optional parameters are marked in the parameter table, along with the value used when you omit them.
Each function runs at sync time, against the data in your connected Catsy account and your iPaaS.com subscription.
The functions are grouped below by the area of the integration they support.
Categories
GetCatsyCategoryIdsFromCategories
What it does: Maps a set of iPaaS.com categories to their Catsy category IDs and returns one of them, either the ID at the position you specify or the last mapped ID.
Signature: Task<string> GetCatsyCategoryIdsFromCategories(object categories, int? index = -1)
How to call it: await GetCatsyCategoryIdsFromCategories(categories)
Parameter | Type | Required | Default | Description |
|
| Yes | N/A | The iPaaS.com categories to map to Catsy category IDs. |
|
| No |
| The zero-based position of the Catsy category ID to return. When omitted (or |
Returns: string. The Catsy category ID at the requested position, or the last mapped Catsy category ID when no valid index is given. Returns null if no categories are supplied.
Example: For three iPaaS.com categories with index of 2, the third mapped Catsy category ID is returned.
When to use it: Use this when a Catsy product field needs a single Catsy category ID resolved from the product's iPaaS.com categories.
GetCategories
What it does: Takes a list of category names and returns each name paired with its iPaaS.com category ID.
Signature: Task<object> GetCategories(object categories)
How to call it: await GetCategories(categories)
Parameter | Type | Required | Default | Description |
|
| Yes | N/A | The list of category names to resolve to iPaaS.com category IDs. |
Returns: object. A list of categories, each with its iPaaS.com category ID and name. Names that cannot be resolved are skipped.
Example: ["Shoes", "Electronics", "Accessories"] returns each name paired with its iPaaS.com category ID.
When to use it: Use this when a mapping needs the iPaaS.com category ID for one or more category names.
Product Tags
GetOrCreateTag
What it does: Checks a list of product tags against Catsy and creates any that do not yet exist, then returns the full list of tags present in Catsy.
Signature: Task<List<string>> GetOrCreateTag(List<string> tags)
How to call it: await GetOrCreateTag(tags)
Parameter | Type | Required | Default | Description |
|
| Yes | N/A | The tag names to validate against Catsy. Any tag that does not already exist is created. |
Returns: List<string>. The consolidated list of Catsy product tags (existing plus any newly created). Returns null if the existing tags cannot be retrieved.
Example: ["Summer", "Sale", "Exclusive"] returns the same tags, creating any that were missing in Catsy.
When to use it: Use this when a Catsy product should be tagged and you want the integration to create any tags that are not already defined in Catsy.
Custom Fields
GetAdditionalPropertyValue
What it does: Reads a value from a record's additional properties by matching on a key. It accepts either a list of custom fields or a dictionary and returns the matching value.
Signature: object GetAdditionalPropertyValue(object additionalProperties, string matchKey)
How to call it: GetAdditionalPropertyValue(additionalProperties, matchKey)
Parameter | Type | Required | Default | Description |
|
| Yes | N/A | A list of custom fields, or a dictionary of additional properties, to search. |
|
| Yes | N/A | The key whose value should be returned. |
Returns: object. The value matched to the key. Multi-value entries are returned as a comma-separated string, and an empty string is returned when the key is not found.
Example: With additional properties [{"Name": "Color", "Value": "Red"}] and a matchKey of "Color", the function returns "Red".
When to use it: Use this to pull a single custom-field or additional-property value into a mapping by its key.