Schedules endpoint
Schedules are a tool that can be used to automatically run batch segmentation jobs once a day. You can use the /config/schedules endpoint to retrieve a list of schedules, create a new schedule, retrieve details of a specific schedule, update a specific schedule, or delete a specific schedule.
Getting started
The endpoints used in this guide are part of the Adobe Experience Platform Segmentation Service API. Before continuing, please review the getting started guide for important information that you need to know in order to successfully make calls to the API, including required headers and how to read example API calls.
Retrieve a list of schedules retrieve-list
You can retrieve a list of all schedules for your organization by making a GET request to the /config/schedules endpoint.
API format
The /config/schedules endpoint supports several query parameters to help filter your results. While these parameters are optional, their use is strongly recommended to help reduce expensive overhead. Making a call to this endpoint with no parameters will retrieve all schedules available for your organization. Multiple parameters can be included, separated by ampersands (&).
GET /config/schedules
GET /config/schedules?start={START}
GET /config/schedules?limit={LIMIT}
{START}{LIMIT}Request
The following request will retrieve the last ten schedules posted within your organization.
curl -X GET https://platform.adobe.io/data/core/ups/config/schedules?limit=10 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with a list of schedules for the specified organization as JSON.
{
"_page": {
"totalCount": 10,
"pageSize": 1
},
"children": [
{
"id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "Batch Segmentation",
"state": "active",
"type": "batch_segmentation",
"schedule": "0 0 1 * * ?",
"properties": {
"segments": []
},
"createEpoch": 1573158851,
"updateEpoch": 1574365202
}
],
"_links": {
"next": {}
}
}
_page.totalCount_page.pageSizechildren.namechildren.typechildren.propertieschildren.properties.segments["*"] ensures all segments are included.children.schedulechildren.stateCreate a new schedule create
You can create a new schedule by making a POST request to the /config/schedules endpoint.
API format
POST /config/schedules
Request
curl -X POST https://platform.adobe.io/data/core/ups/config/schedules \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '
{
"name":"profile-default",
"type":"batch_segmentation",
"properties":{
"segments":[
"*"
]
},
"schedule":"0 0 1 * * ?",
"state":"inactive"
}'
nametypepropertiesproperties.segmentstype equals “batch_segmentation”. Using ["*"] ensures all segments are included.scheduleIf this string is not supplied, a system-generated schedule will be automatically generated.
stateResponse
A successful response returns HTTP status 200 with details of your newly created schedule.
{
"id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "{SCHEDULE_NAME}",
"state": "inactive",
"type": "batch_segmentation",
"schedule": "0 0 1 * * ?",
"properties": {
"segments": [
"*"
]
},
"createEpoch": 1568267948,
"updateEpoch": 1568267948
}
Retrieve a specific schedule get
You can retrieve detailed information about a specific schedule by making a GET request to the /config/schedules endpoint and providing the ID of the schedule you wish to retrieve in the request path.
API format
GET /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id value of the schedule you want to retrieve.Request
curl -X GET https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 200 with detailed information about the specified schedule.
{
"id": "4e538382-dbd8-449e-988a-4ac639ebe72b",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e7e17720-c5bb-11e9-aafb-87c71c35cac8",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "{SCHEDULE_NAME}",
"state": "inactive",
"type": "batch_segmentation",
"schedule": "0 0 1 * * ?",
"properties": {
"segments": [
"*"
]
},
"createEpoch": 1568267948,
"updateEpoch": 1568267948
}
nametypebatch_segmentation and export.propertiesproperties.segments["*"] ensures all segments are included.schedulestateactive and inactive. By default, the state is set to inactive.Update details for a specific schedule update
You can update a specific schedule by making a PATCH request to the /config/schedules endpoint and providing the ID of the schedule you are trying to update in the request path.
The PATCH request allows you to update either the state or the cron schedule for an individual schedule.
Update schedule state update-state
You can use a JSON Patch operation to update the state of the schedule. To update the state, you declare the path property as /state and set the value to either active or inactive. For more information about JSON Patch, please read the JSON Patch documentation.
API format
PATCH /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id value of the schedule you want to update.Request
curl -X PATCH https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '
[
{
"op": "add",
"path": "/state",
"value": "active"
}
]'
pathpath to “/state”.valueResponse
A successful response returns HTTP status 204 (No Content).
Update cron schedule update-schedule
You can use a JSON Patch operation to update the cron schedule. To update the schedule, you declare the path property as /schedule and set the value to a valid cron schedule. For more information about JSON Patch, please read the JSON Patch documentation. For more information about cron schedules, please read the appendix on the cron expression format.
API format
PATCH /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id value of the schedule you want to update.Request
curl -X PATCH https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '
[
{
"op":"add",
"path":"/schedule",
"value":"0 0 2 * * ?"
}
]'
pathpath to /schedule.valueResponse
A successful response returns HTTP status 204 (No Content).
Delete a specific schedule
You can request to delete a specific schedule by making a DELETE request to the /config/schedules endpoint and providing the ID of the schedule you wish to delete in the request path.
API format
DELETE /config/schedules/{SCHEDULE_ID}
{SCHEDULE_ID}id value of the schedule you want to delete.Request
curl -X DELETE https://platform.adobe.io/data/core/ups/config/schedules/4e538382-dbd8-449e-988a-4ac639ebe72b \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Response
A successful response returns HTTP status 204 (No Content).
Next steps
After reading this guide you now have a better understanding of how schedules work.
Appendix appendix
The following appendix explains the format of cron expressions used in schedules.
Format
A cron expression is a string that is made up of 6 or 7 fields. The expression would look something similar to the following:
0 0 12 * * ?
In a cron expression string, the first field represents the seconds, the second field represents the minutes, the third field represents the hours, the fourth field represents the day of the month, the fifth field represents the month, and the sixth field represents the day of the week. You can also optionally include a seventh field, which represents the year.
, - * /, - * /, - * /, - * ? / L W, - * /, - * ? / L #, - * /SUN is equivalent to using sun.The special characters allowed represent the following meanings:
** in the hours field would mean every hour.?3 in the day of the month field and ? in the day of the week field.-9-15 in the hours field, this would mean the hours would include 9, 10, 11, 12, 13, 14, and 15.,MON, FRI, SAT in the day of the week field, this would mean the days of the week would include Monday, Friday, and Saturday.// determines where it increments from, while the value placed after the / determines how much it increments by. For example, if you put 1/7 in the minutes field, this would mean that the minutes would include 1, 8, 15, 22, 29, 36, 43, 50, and 57.LLast, and has a different meaning depending on which field it is used by. If it is used with the day of the month field, it represents the last day of the month. If it is used with the day of the week field by itself, it represents the last day of the week, which is Saturday (SAT). If it is used with the day of the week field, in conjunction with another value, it represents the last day of that type for the month. For example, if you put 5L in the day of the week field, it would only include the last Friday of the month.W18W in the day of the month field, and the 18th of that month was a Saturday, it would trigger on Friday the 17th, which is the closest weekday. If the 18th of that month was a Sunday, it would trigger on Monday the 19th, which is the closest weekday. Please note that if you put 1W in the day of the month field, and the closest weekday would be in the previous month, the event will still trigger on the closest weekday of the current month.Additionally, you can combine
L and W to make LW, which would specify the last weekday of the month.## represents the day of the week, while the value placed after the # represents which occurrence in the month it is. For example, if you put 1#3, the event would trigger on the third Sunday of the month. Please note that if you put X#5 and there is no fifth occurrence of that day of the week in that month, the event will not be triggered. For example, if you put 1#5, and there is no fifth Sunday in that month, the event will not be triggered.Examples
The following table shows sample cron expression strings and explains what they mean.
0 0 13 * * ?0 30 9 * * ? 20220 * 18 * * ?0 0/10 17 * * ?0 13,38 5 ? 6 WED0 30 12 ? * 4#30 30 12 ? * 6L0 45 11 ? * MON-THU