Skip to main content

Schedule a build

You can use the CI/CD Manager API to create schedules for InsuranceSuite applications, Digital applications, and Guidewire Testing Framework (GT: Framework).

All sample requests in this guide include the following path parameters:

Parameter nameDescription
tenantIdTenant ID.
starSystemIdID of the GCC star system (project) that includes the application for which you create a schedule.
applicationIdApplication for which you create a schedule:
- PC for PolicyCenter
- BC for BillingCenter
- CC for ClaimCenter
- CM for ContactManager
- PORTALS for Digital applications
- GT_FRAMEWORK for Guidewire Testing Framework
buildScheduleIdSchedule ID.

About schedules

By creating a schedule, you can configure one or more TeamCity builds to run automatically at a specific time. You can create multiple schedules for each application.

note

You can create up to 20 schedules. This number includes both active and inactive schedules across all your projects.

Schedule definition

Example of a schedule
{
"name": "Daily PC build",
"enabled": false,
"id": "afcd3b9e11774f56a61ffee1763ebce7",
"branchFilter": "+:<default>",
"withPendingChangesOnly": false,
"cron": {
"seconds": "0",
"minutes": "0",
"hours": "12",
"dayOfMonth": "*",
"dayOfWeek": "?",
"month": "*",
"year": "*",
"timezone": "US/Pacific"
},
"builds": [
{
"buildType": "DOCKERIZE_IS",
"predefinedParameters": {},
"customParameters": {}
}
]
}

Parameters

NameTypeDescription
namestringSchedule name.
enabledBooleanIndicates whether the schedule is active.
idstringSchedule ID.
branchFilterstringDefines branches on which the scheduled builds will run.
withPendingChangesOnlyBooleanIndicates whether to trigger builds only on branches with pending changes.
cronobjectSpecifies when to run a schedule.
buildsarraySpecifies TeamCity builds included in the schedule and, optionally, their configuration.

Name and ID

When creating a schedule, you must define its name. Schedule name must be unique at application level and no longer than 255 characters.

Schedule ID is generated automatically. If you pass the id parameter in a request body, its value is ignored.

Branch filter

Use the branchFilter parameter to specify branches on which the scheduled builds will run:

  • To include a branch, use +:branch_name.
  • To exclude a branch, use -:branch_name.
  • To separate rules, use a newline character: \n.
  • You can use a wildcard *.
  • Branch names are case-sensitive.

For example:

  • Include all branches:
"branchFilter": "+:*"
  • Include only a default branch:
"branchFilter": "+:<default>"
  • Include all branches except for the the default one:
"branchFilter": "+:*\n-:<default>"
  • Include all branches prefixed with feature-:
"branchFilter": "+:feature-*"

Cron expression

To specify when and how often to run a schedule, use the cron parameter.

cron is an object representation of the Quartz cron expression with one additional field: timezone:

FieldPossible valuesSpecial charactersDefault value
seconds0–59, - * /0
minutes0–59, - * /0
hours0–23, - * /*
dayOfMonth1–31, - * / ? L W*
month1–12 or JAN–DEC, - * /*
dayOfWeek1–7 or SUN-SAT, - * / ? L #?
year1970-2099 or null, - * /*
timezoneTime zone name
according to the time zone database
GMT
note

For dayOfWeek, 1 represents Sunday, 2 represents Monday, etc.

For example, you can set your schedule to run:

  • Every day at 12:00 p.m. GMT
{
"dayOfMonth": "*",
"dayOfWeek": "?",
"hours": "12",
"minutes": "0",
"month": "*",
"seconds": "0",
"timezone": "GMT",
"year": "*"
}
  • Every Monday, Tuesday, Wednesday, Thursday, and Friday at 10:15 a.m. GMT
{
"dayOfMonth": "?",
"dayOfWeek": "MON-FRI",
"hours": "10",
"minutes": "15",
"month": "*",
"seconds": "0",
"timezone": "GMT",
"year": "*"
}
  • On the third Friday of every month at 10:15 a.m. PST
{
"dayOfMonth": "?",
"dayOfWeek": "6#3",
"hours": "10",
"minutes": "15",
"month": "*",
"seconds": "0",
"timezone": "US/Pacific",
"year": "*"
}
  • Every 5 minutes between 2:00 p.m. and 2:55 p.m. GMT, then every 5 minutes between 6:00 p.m. and 6:55 p.m. GMT every day
{
"dayOfMonth": "*",
"dayOfWeek": "?",
"hours": "14,18",
"minutes": "0/5",
"month": "*",
"seconds": "0",
"timezone": "GMT",
"year": "*"
}
  • In 2024, every day at 10:15 a.m. PST
{
"dayOfMonth": "*",
"dayOfWeek": "?",
"hours": "10",
"minutes": "15",
"month": "*",
"seconds": "0",
"timezone": "US/Pacific",
"year": "2024"
}

Builds

A schedule can consist of multiple builds as long as they apply to the same application. To specifiy the TeamCity builds included in the schedule, use the builds property.

The builds property is an array of objects that represent TeamCity builds and their configuration. Each object includes the following properties:

PropertyDescription
buildTypeA TeamCity build.
predefinedParametersA custom configuration of a build:
- The structure of this property depends on the build type.
- When optional and not specified, a default build configuration is used.
customParametersAdditional custom parameters. A key-value map of strings where key is a custom parameter name.

For example, a shedule that includes smoke tests with default configuration and server tests with custom configuration, might look like this:

"builds": [
{
"buildType": "SMOKE_TEST",
"predefinedParameters": {},
"customParameters": {}
}
{
"buildType": "SERVER_TEST",
"predefinedParameters": {
"preMergeSuites": "gw.suites.ExampleSuite, gw.suites.AnotherSuite",
"postMergeSuites": "gw.suites.SomeTestSuite"
},
"customParameters": {}
}
]

Create a schedule

To schedule builds for an application, send the following POST request:

curl -X 'POST' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{body}'

Where {body} contains a schedule definition.

For example, to schedule a Dockerize Application build with default configuration to run on the default branch every day at noon CET, use the following:

Request body
{
"name": "Daily Dockerize Build",
"enabled": true,
"branchFilter": "+:<default>",
"withPendingChangesOnly": false,
"cron": {
"seconds": "0",
"minutes": "0",
"hours": "12",
"dayOfMonth": "*",
"dayOfWeek": "?",
"month": "*",
"year": "*",
"timezone": "CET"
},
"builds": [
{
"buildType": "DOCKERIZE_IS",
"predefinedParameters": {},
"customParameters": {}
}
]
}

Response contains your new schedule configuration:

Example response
{
"name": "Daily Dockerize Build",
"enabled": true,
"id": "afcd3b9e11774f56a61ffee1763ebce7",
"branchFilter": "+:<default>",
"withPendingChangesOnly": false,
"cron": {
"seconds": "0",
"minutes": "0",
"hours": "12",
"dayOfMonth": "*",
"dayOfWeek": "?",
"month": "*",
"year": "*",
"timezone": "CET"
},
"builds": [
{
"buildType": "DOCKERIZE_IS",
"predefinedParameters": {},
"customParameters": {}
}
]
}

Customize build parameters

By default, scheduled builds use the parameter values configured in a TeamCity project for a selected application. You can customize this configuration with the predefinedParameters and customParameters properties. For details, see Builds.

info

Customized parameters apply only to the scheduled builds. Defining the predefinedParameters and customParameters properties does not override the default configuration of your builds.

Verify changes in TeamCity

Each schedule appears in a TeamCity project for your application as a separate composite build with the schedule name. Builds included in the schedule are listed in brackets.

Schedules in TeamCity

To verify a schedule configuration in TeamCity:

  1. Select an application for which you created a schedule.
  2. In Schedules, find and select a composite build with your schedule name.
  3. Go to the Settings tab.
  4. In the table, check the new Schedule Trigger:

Scheduled trigger list in Teamcity


Get created schedule

To retrieve configuration of a specific schedule, send the following GET request:

curl -X 'GET' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules/{buildScheduleId}' \
-H 'accept: application/json' \
-H 'Authorization: Bearer {access_token}'

Response contains a JSON object with the schedule configuration, for example:

Example response
{
"name": "Daily Dockerize Build",
"enabled": true,
"id": "afcd3b9e11774f56a61ffee1763ebce7",
"branchFilter": "+:<default>",
"withPendingChangesOnly": false,
"cron": {
"seconds": "0",
"minutes": "0",
"hours": "12",
"dayOfMonth": "*",
"dayOfWeek": "?",
"month": "*",
"year": "*",
"timezone": "CET"
},
"builds": [
{
"buildType": "DOCKERIZE_IS",
"predefinedParameters": {},
"customParameters": {}
}
]
}

Modify a schedule

You can modify all settings except for an application to which a schedule applies.

Update date and time

To change the date and time details for a schedule, send the following PATCH request:

curl -X 'PATCH' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules/{buildScheduleId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json-patch+json' \
-d '{body}'

Where {body} contains an updated cron object. Follow the JSON Patch format.

For example, to modify a schedule to run every Friday at 3:15 p.m. CET, use the following:

Request body
[
{
"op": "replace",
"path": "/cron",
"value": {
"seconds": "0",
"minutes": "15",
"hours": "15",
"dayOfMonth": "?",
"dayOfWeek": "6",
"month": "*",
"year": "*",
"timezone": "CET"
}
}
]

For a successful request, you will receive the 200 status code.

To verify these changes in TeamCity:

  1. Select an application for which you created a schedule.
  2. In Schedules, find and select a composite build with your schedule name.
  3. Go to the Schedules tab.
  4. In the table, check Parameters Description and the updated cron command for the modified Schedule Trigger:

Updated schedule trigger in TeamCity.

Make builds run only if there are pending changes

By default, builds run according to the schedule even if there are no changes in your code. To change this behavior and trigger builds only if there are pending changes in your code, send the following PATCH request:

curl -X 'PATCH' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules/{buildScheduleId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json-patch+json' \
-d '{body}'

Where {body} contains an updated schedule configuration. Follow the JSON Patch format:

Request body
[
{
"op": "replace",
"path": "/withPendingChangesOnly",
"value": true
}
]

For a successful request, you will receive the 200 status code.

To verify these changes in TeamCity:

  1. Select an application for which you created a schedule.
  2. In Schedules, find and select a composite build with your schedule name.
  3. Go to the Schedules tab.
  4. In the table, check Parameters Description for the modified Schedule Trigger:

Schedule trigger with updated settings.

Update branch filter

To change the branch on which the scheduled builds run, use the following PATCH request:

curl -X 'PATCH' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules/{buildScheduleId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json-patch+json' \
-d '{body}'

Where {body} contains an updated schedule configuration. Follow the JSON Patch format.

For example, to run scheduled builds on all branches except for the default one, use the following:

Request body
[
{
"op": "replace",
"path": "/branchFilter",
"value": "+:*\n-:<default>"
}
]

For a successful request, you will receive the 200 status code.

To verify these changes in TeamCity:

  1. Select an application for which you created a schedule.
  2. In Schedules, find and select a composite build with your schedule name.
  3. Go to the Settings tab.
  4. In the table, check Parameters Description for the modified Schedule Trigger:

Updated schedule trigger in TeamCity.


Deactivate a schedule

Instead of deleting a schedule, you can deactivate it. This way, you save the schedule configuration so you can activate it again when ready.

note

You can create up to 20 schedules. This number includes both active and inactive schedules across all your projects.

To deactivate a schedule, send the following PATCH request:

curl -X 'PATCH' \
'{baseUrl}/api/v2/tenants/{tenantId}/starsystems/{starSystemId}/cicd-configs/{applicationId}/build-schedules/{buildScheduleId}' \
-H 'Accept: */*' \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json-patch+json' \
-d '{body}'

Where {body} contains an updated schedule configuration. Follow the JSON Patch format:

Request body
[
{
"op": "replace",
"path": "/enabled",
"value": false
}
]

For a successful request, you will receive the 200 status code.

Verify changes in TeamCity

Once you deactivate a schedule, you can verify changes in TeamCity:

  1. Select an application for which you created a schedule.
  2. In Schedules, find and select a composite build with your schedule name.
  3. Go to the Settings tab.
  4. In the Triggers section, you don't have any configured schedule triggers:

Disabled trigger in TeamCity.