Introduction
This guide explains how to obtain authentication details from Apple, as well as how to install an Apple iCloud Contacts Connector.
Setup & Authentication
Remote Setup in Apple iCloud Contacts – performed by your customer
Your customer should go to their Apple account and generate an app-specific password.
See Apple’s instructions on how to do this.
Cyclr Connector Installation
When installing an Apple iCloud Contacts Connector, the following values are used:
| Property | Description |
|---|---|
| Apple ID | The Apple account to login with. |
| App-specific password | The app-specific password for the Apple account. |
Additional Information
item* properties
Several contact properties are returned inside “item*” elements.
These elements do not have a fixed order and, for example, the same address property may be returned under a different item element from one contact to another.
To map item* properties use the following formats:
Contacts > Get Contact
<Item#>.<ItemKey>.value<Item#>.<ItemKey>.params.[<ParamKey>]
For example, when getting a contact which has an Item# of item1 which contains an ItemKey of ADR which has a ParamKey of TYPE map:
item1.ADR.valueitem1.ADR.params.[TYPE]
Contacts > List Contacts
multistatus.[response].object.<Item#>.<ItemKey>.valuemultistatus.[response].object.<Item#>.<ItemKey>.params.[<ParamKey>]
For example, when list contacts which have an Item# of item1 which contains an ItemKey of ADR which has a ParamKey of TYPE map:
multistatus.[response].object.item1.ADR.valuemultistatus.[response].object.item1.ADR.params.[TYPE]
Contacts > Upsert Contact
<Item#>.<ItemKey>.value<Item#>.<ItemKey>.params.[<ParamKey>]
For example, when creating a contact which has an Item# of item1 which contains an ItemKey of ADR which has a ParamKey of TYPE map:
item1.ADR.valueitem1.ADR.params.[TYPE]
“List Changed Contacts” Method Explanation
Due to the way this system’s API functions, the Contacts > List Changed Contacts Method works a little differently to other Connector Methods.
When the Method runs, the “ETag” tag value of each contact is stored on the Apple iCloud Contacts Connector’s internal storage. Subsequent runs of a Step will compare these cached Etags to the current ETags to determine the changes to the contacts that have occurred.
This cache is ONLY updated when a Template or Cycle is executed and a Transaction reaches a Step using the “List Changed Contacts” Step.
The cache is NOT updated when clicking the Step’s Test Step button, or when running the Method on the Connector’s Settings page. This is to avoid missing any changes to contacts that may occur when checking what data the Method will return, perhaps the next time it runs within a Cycle.
The first run of the “List Changed Contacts” Method, including the first run after running the Contacts > Reset Changed Contacts Method which cleared the cache (described below), will always return all contacts as if they had been “created” since the last run.
Clearing the Cache
Should you have a need to clear this cached data for any reason, perhaps to begin retrieving changed contacts from the start again, you can execute the Contacts > Reset Changed Contacts Method.
The cache is ONLY cleared when a Template or Cycle is executed and a Transaction reaches a Step using the “Reset Changed Contacts” Step, or the “Reset Changed Contacts” Method is run on the Connector’s Settings page.