The articles in this section describe how to use the Cyclr API to set the different mapping options available on a step.
You must already have a Cyclr API Access Token.
Mappings Overview #
When setting a mapping on a Step through the Cyclr API, you will need to identify whether you’re mapping to a Parameter or a Field.
You can do this by retrieving a Step using one of these endpoints:
GET /v1.0/cycles/{id}/stepsGET /v1.0/cycles/{id}/steps/{stepId}
The Responses from those endpoints include a Method property which contains details of the Connector Method used by the Step.
You can then check witin the Method property’s Parameters and RequestFields for the particular item you wish to map to:
- If it’s within the
Parametersproperty, it’s a Parameter and can be modified using/v1.0/steps/{id}/parametersendpoints. - If it’s within the
RequestFieldsproperty, it’s a Field and can be modified using/v1.0/steps/{id}/fieldmappingsendpoints
Using an ID of the wrong type with these endpoints will return an error.
Step Prerequisites #
Templates in Cyclr may include steps that require mapping or parameter values that are specific to your end user’s use of those templates.
If the Cycle prerequisites method returned Steps that required mapping, you need to loop through them to determine what is required.
Request:
GET /steps/{Step ID}/prerequisites
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000Response:
[{
"ReasonCode": 40,
"Reason": "Missing parameter mapping",
"ObjectType": "Parameter",
"ObjectId": 16017
},
{
"ReasonCode": 41,
"Reason": "Missing field mapping",
"ObjectType": "ConnectorFieldMapping",
"ObjectId": 283792
},
{
"ReasonCode": 41,
"Reason": "Missing field mapping",
"ObjectType": "ConnectorFieldMapping",
"ObjectId": 283793
},
{
"ReasonCode": 41,
"Reason": "Missing field mapping",
"ObjectType": "ConnectorFieldMapping",
"ObjectId": 283794
},
{
"ReasonCode": 41,
"Reason": "Missing field mapping",
"ObjectType": "ConnectorFieldMapping",
"ObjectId": 283795
},
{
"ReasonCode": 41,
"Reason": "Missing field mapping",
"ObjectType": "ConnectorFieldMapping",
"ObjectId": 283796
}
]
Map Parameters #
Step Parameters are passed as a header or part of the URL (hostname, path, or query string parameters) to the third party API endpoint.
Get Parameter details #
For each missing Parameter Mapping returned by the step prerequisites request:
GET /v1.0/steps/{Step ID}/parameters/{Parameter ID}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000 {
"Parameter": {
"Id": 16017,
"Name": "List ID",
"Description": "Select a List.",
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": "Lookup List",
"Values": [],
"DisplayOrder": 1,
"Triggers": [{
"AccountConnectorId": 36329,
"MethodId": 36666,
"Name": "Lookup List",
"HumanReadableKey": "[lists].name",
"IdentifierKey": "[lists].id",
"SubTriggers": [],
"EntityId": 16017
}]
},
"IsEntityIdentifier": false,
"MappingType": null,
"SourceFieldId": null,
"SourceStepId": null,
"TriggerValue": null,
"TriggerValueDisplayName": null,
"Value": null
}In the example above, the Triggers array provides directions as to the source of valid values.
In this example the method 36666 of Account Connector 36329 should be called, with the [lists].name values presented to the user for selection and the [lists].id value used as the actual parameter value.
Retrieve Values #
Values can be retrieved from the trigger by calling the identified trigger method as below:
GET /v1.0/account/connectors/36329/methods/36666
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000 {
"lists": [{
"id": "a78f86e7d7",
"web_id": 227621,
"name": "Newsletter Subscribers",
"contact": {
"company": "Acme Inc",
"address1": "1 Commercial Road",
"address2": "",
"city": "Eastbourne",
"state": "East Sussex",
"zip": "BN21 3XQ",
"country": "GB",
"phone": "+44 (0)330 354 2525"
},
"permission_reminder": "You are receiving this email as a subscriber to our regular newsletters. If you unsubscribe you will miss important news and announcements.",
"use_archive_bar": true,
"campaign_defaults": {
"from_name": "Acme Inc",
"from_email": "news@acmeinc.com",
"subject": "",
"language": "en"
},
"notify_on_subscribe": "hello@cyclr.com",
"notify_on_unsubscribe": "hello@cyclr.com",
"date_created": "2016-08-22T09:46:58+00:00",
"list_rating": 0,
"email_type_option": false,
"subscribe_url_short": "http://eepurl.com/ABC123",
"subscribe_url_long": "https://cyclr.us5.list-manage.com/subscribe?u=534685638659&id=84378947",
"beamer_address": "us5-f578sd58f-cb2bd1adc8@inbound.mailchimp.com",
"visibility": "pub",
"modules": [],
"stats": {
"member_count": 723,
"unsubscribe_count": 12,
"cleaned_count": 0,
"member_count_since_send": 2,
"unsubscribe_count_since_send": 0,
"cleaned_count_since_send": 0,
"campaign_count": 2,
"campaign_last_sent": "",
"merge_field_count": 2,
"avg_sub_rate": 0,
"avg_unsub_rate": 0,
"target_sub_rate": 0,
"open_rate": 100,
"click_rate": 100,
"last_sub_date": "2016-08-22T11:36:09+00:00",
"last_unsub_date": ""
},
"_links": []
}]
}
This response can then be used to present the user with valid options.
In this example there is a single value to present to the user, Newsletter Subscribers, with a corresponding value to pass to Cyclr as the parameter value a78f86e7d7.
Step Setup Map fields #
Field Mappings are passed to the third party API as the request body.
For each missing field mapping returned in the Step prerequisites:
Request:
GET /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000Response:
{
"Field": {
"Id": 283792,
"Name": "Email",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": [],
"DisplayOrder": 1,
"Triggers": []
},
"MappingType": "Ignore",
"SourceFieldId": null,
"SourceStepId": null,
"TriggerValue": null,
"TriggerValueDisplayName": null,
"Value": null
}The IsOptional property indicates if a field mapping is optional or required before the Cycle can run.
There are multiple ways of setting a Field Mapping value.
Map Fields with static values #
A static value can be set as the field mapping, a static value is a value that will never change.
This value should be obtained from your user, or automatically assigned by your application, then provided to Cyclr as below:
Request:
PUT /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000
{
"MappingType": "StaticValue",
"Value": "MyStaticValue"
}Response:
{
"Field": {
"Id": 283792,
"Name": "Email",
"Description": null,
"IsOptional": false,
"DataType": undefined,
"TriggerName": null,
"Values": [],
"DisplayOrder": 1,
"Triggers": []
},
"MappingType": "StaticValue",
"SourceFieldId": null,
"SourceStepId": null,
"TriggerValue": null,
"TriggerValueDisplayName": null,
"Value": "MyStaticValue"
}Map Fields with Step data #
A Step Data mapping uses a value from a previous step response as the value for this steps request.
Cyclr provides an endpoint to discover valid field mapping options for a given step.
Request:
GET /v1.0/steps/{Step ID}/fieldsformapping
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000Response:
[{
"Id": 283797,
"Name": "Member ID",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283798,
"Name": "Email",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283799,
"Name": "Status",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283800,
"Name": "Average Open Rate",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283801,
"Name": "Average Click Rate",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283802,
"Name": "Member Rating",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283803,
"Name": "Language",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283804,
"Name": "Unique Email ID",
"Description": null,
"IsOptional": false,
"DataType": "Text",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283805,
"Name": "Email Type",
"Description": null,
"IsOptional": false,
"DataType": "Text",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283806,
"Name": "IP Signup Address",
"Description": null,
"IsOptional": false,
"DataType": "Text",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283807,
"Name": "Signup Timestamp",
"Description": null,
"IsOptional": false,
"DataType": "DateTime",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283808,
"Name": "Opt-In Timestamp",
"Description": null,
"IsOptional": false,
"DataType": "DateTime",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283809,
"Name": "List ID",
"Description": null,
"IsOptional": false,
"DataType": "Text",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
},
{
"Id": 283810,
"Name": "Opt-In IP",
"Description": null,
"IsOptional": false,
"DataType": "Text",
"TriggerName": null,
"Values": null,
"DisplayOrder": 0,
"Triggers": []
}
]
Map Fields from a list of values #
Fields within a step may contain a set of pre-defined values that can be selected from, returned in the “Values” array below:
Get field values #
GET /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000 {
"Field": {
"Id": 283792,
"Name": "Email",
"Description": null,
"IsOptional": false,
"DataType": "Undefined",
"TriggerName": null,
"Values": [
"List Option 1",
"List Option 2",
"List Option 3"
],
"DisplayOrder": 1,
"Triggers": []
},
"MappingType": "Ignore",
"SourceFieldId": null,
"SourceStepId": null,
"TriggerValue": null,
"TriggerValueDisplayName": null,
"Value": null
}Update Field values #
For these steps, the list of valid values should be presented to your user for them to make a selection. Their selection should then be used to update the field value.
POST /v1.0/steps/{Step ID}/fieldmappings/{Field ID}
Authorization Bearer ********************
X-Cyclr-Account: 00000000-0000-0000-0000-000000000000
{
"MappingType": "ValueList",
"Value": "List Option 1"
} {
"Field": {
"Id": 283792,
"Name": "Email",
"Description": null,
"IsOptional": false,
"DataType": undefined,
"TriggerName": null,
"Values": [],
"DisplayOrder": 1,
"Triggers": []
},
"MappingType": "ValueList",
"SourceFieldId": null,
"SourceStepId": null,
"TriggerValue": null,
"TriggerValueDisplayName": null,
"Value": "List Option 1"
}
