Skip to main content
Planview Customer Success Center

Create a card automation

POST /io/board/:boardId/automation

Create a card automation.

Request Properties

Param Type Usage Default
actionType* integer List of action type values
1 (Web service call)
2 (Post to Slack)
3 (Post to Microsoft Teams)
4 (Copy Card)
5 (Move Card)
6 (Trigger GitHub Action)
7 (Update Card)
description* string A description or name for the card automation
enabled* boolean Is the card automation currently active
configuration* object Configuration object describing the automation
configuration.cardTypes string array Filter cards on this list of card type ids
configuration.lanes string array Filter cards on this list of lane ids
configuration.priorities enumeration array Filter cards on this list of priorities. Possible values are
normal
low
high
critical
configuration.tags string array List of tags to filter cards
configuration.isBlocked boolean or null Filter cards on block status
configuration.dateFilter object Filter that allows identifying cards based on their Last Activity date, Last Move date, Planned Start Date, or Planned Finish Date
configuration.dateFilter.field enumeration Filter on a card date. Possible values are
none
lastActivity
lastMove
plannedStartDate
plannedFinishDate
configuration.dateFilter.comparison enumeration How to compare the card's date with the current date when an automation is being evaluated. The isEmpty value does not apply to lastActivity or lastMove as they will always have a value. Possible values are
greaterThan
lessThen
equalTo
isEmpty
plannedFinishDate
configuration.dateFilter.direction enumeration How to apply the comparision. The daysAfterNow value does not apply to lastActivity or lastMove, as those dates will always be in the past. Possible values are
daysBeforeNow
daysAfterNow
configuration.dateFilter.value integer The number of days to use in the comparison
configuration.dateFilter.olsonTimeZone string One of valid timezones.
configuration.events* enumeration array A list of events that should trigger this automation to be evaluated against matching cards. Possible values are
movedTo
movedFrom
blocked
unblocked
create
delete
childrenComplete
firstChildStarted
childrenUnblocked
childBlocked
update
scheduled
configuration.schedule object Scheduling information for when scheduled is one of the triggering events
configuration.timeOfDayUtc string The time of day in UTC. Example 09:05.
configuration.daysOfTheWeek string array The days of the week that this scheduled automation should run. Possible values are
sunday
monday
tuesday
wednesday
thursday
friday
saturday
configuration.action* object Details about the action to run when an the automation is triggered for a card
configuration.action.url (Web Service Call) string The URL destination for a web service call
configuration.action.contentType (Web Service Call) enumeration The content type to use as part of the request. Possible values are
application/json
application/x-www-form-urlencoded
configuration.action.url (Post to Slack) string The Slack incoming webhook URL
configuration.action.messagePrefix (Post to Slack) string A heading to include in the message
configuration.action.includeDescription (Post to Slack) boolean Determines if the card description is included in the message
configuration.action.url (Post to Teams) string The Microsoft Teams incoming webhook URL
configuration.action.messagePrefix (Post to Teams) string A heading to include in the message
configuration.action.includeDescription (Post to Teams) boolean Determines if the card description is included in the message
configuration.action.destinationBoardId (Copy Card) string Create the copied card on this board id
configuration.action.destinationLaneId (Copy Card) string Create the copied card in this lane
configuration.action.createConnectionOption (Copy Card) enumeration Connection options for the copied card. Possible values are
none
child (create the copied card as a child of the original)
parent (create the copied card as a parent of the original)
configuration.action.destinationBoardId (Move Card) string Move the card to this board id
configuration.action.destinationLaneId (Move Card) string Move the card to this lane
configuration.action.priority (Update Card) enumeration or null A priority to set on the card. Possible values are
normal
low
high
critical. Specify null for no change.
configuration.action.cardType (Update Card) string or null Update the card to this card type id. Specify null for no change.
configuration.action.customIcon (Update Card) string or null Update the card with this custom icon id. Specify null for no change.
configuration.action.isBlocked (Update Card) boolean or null Update the card to this block status. Specify null for no change.
configuration.action.blockReason (Update Card) string or null When blocking or unblocking a card use this block reason. "Blocked by Card Automation"
configuration.action.tagsToAdd (Update Card) string array Add this list of tags to the card
configuration.action.tagsToRemove (Update Card) string array Remove this list of tags from the card (if any of the tags are already on the card)
configuration.action.usersToAssign (Update Card) string array Assign this list of user ids to the card
configuration.action.usersToUnassign (Update Card) string array Unassign this list of user ids from the card (if any of the users are assigned)
configuration.action.customFields (Update Card) object array Array of custom field objects in the format { "fieldId": "1234", "value": "myvalue" }. Value can be null, a string, a number, or an array of strings (multi field) depending on the field type.
configuration.action.plannedStart (Update Card) object or null Update the plannedStart field.
configuration.action.plannedStart.mode (Update Card) enumeration Possible values are
clear
relative
earliestChildCardDate
latestChildCardDate.
configuration.action.plannedStart.unit (Update Card) enumeration When mode is relative, select the unit from choices
day
week
month.
configuration.action.plannedStart.value (Update Card) number When mode is relative, select the value to add to the current date in the units selected when the automation runs. Values between -999 and 999 are supported.
configuration.action.plannedStart.olsonTimeZone (Update Card) string or null Provide a time zone to determine the current date when the automation runs to use in calculations.
configuration.action.plannedFinish (Update Card) object or null Update the plannedFinish field.
configuration.action.plannedFinish.mode (Update Card) enumeration Possible values are
clear
relative
earliestChildCardDate
latestChildCardDate.
configuration.action.plannedFinish.unit (Update Card) enumeration When mode is relative, select the unit from choices
day
week
month.
configuration.action.plannedFinish.value (Update Card) number When mode is relative, select the value to add to the current date in the units selected when the automation runs. Values between -999 and 999 are supported.
configuration.action.plannedFinish.olsonTimeZone (Update Card) string or null Provide a time zone to determine the current date when the automation runs to use in calculations.
configuration.action.size (Update Card) object or null Update the size field.
configuration.action.size.mode (Update Card) enumeration Possible values are
clear
specificValue
sumOfChildren.
configuration.action.size.value (Update Card) number When mode is specificValue, select the value to use for size when the automation runs. Values between 1 and 999999999 are supported.
configuration.action.owner.value (GitHub Action) string The GitHub repository owner name, if not using a custom field
configuration.action.owner.customFieldId (GitHub Action) string The id of a card custom field that contains the GitHub repository owner, when useCustomField is true
configuration.action.owner.useCustomField (GitHub Action) boolean Whether to use a custom field on the card to determine the GitHub repository owner
configuration.action.repo.value (GitHub Action) string The GitHub repository name, if not using a custom field
configuration.action.repo.customFieldId (GitHub Action) string The id of a card custom field that contains the GitHub repository name, when useCustomField is true
configuration.action.repo.useCustomField (GitHub Action) boolean Whether to use a custom field on the card to determine the GitHub repository owner
configuration.action.eventType (GitHub Action) string The event_type value to provide to GitHub, which enables differentiating which action to run
secrets object Contains secret information being provided for an action.
secrets.github string GitHub access token to associate with a GitHub Action automation
secrets.signingKey string Key to use as part of signing the body for the x-lk-signature header on a Web Service Call automation

* Required

Example Request

{
    "actionType": 2,
    "description": "Notify on Blocked Cards",
    "enabled": true,
    "configuration": {
        "cardTypes": [
            "10112910837",
            "10112910838",
            "10112910840"
        ],
        "lanes": [
            "10112910647",
            "10112910648"
        ],
        "priorities": [],
        "tags": [],
        "isBlocked": true,
        "events": [
            "scheduled"
        ],
        "action": {
            "url": "https://my-incoming-slack-url.com",
            "messagePrefix": "**Blocked Card**",
            "includeDescription": true
        },
        "schedule": {
            "timeOfDayUtc": "14:00",
            "daysOfTheWeek": [
                "monday",
                "tuesday",
                "wednesday",
                "thursday",
                "friday"
            ]
        }
    }
}

Example Successful Response

201 Created

{
    "cardAutomation": {
        "id": "10135649061",
        "boardId": "10112910528",
        "userId": "25038",
        "description": "Notify on Blocked Cards",
        "enabled": true,
        "events": [
            "scheduled"
        ],
        "schedule": {
            "timeOfDayUtc": "14:00",
            "daysOfTheWeek": [
                "monday",
                "tuesday",
                "wednesday",
                "thursday",
                "friday"
            ]
        },
        "filter": {
            "cardTypes": [
                "10112910837",
                "10112910838",
                "10112910840"
            ],
            "lanes": [
                "10112910647",
                "10112910648"
            ],
            "priorities": [],
            "tags": [],
            "isBlocked": true
        },
        "action": {
            "type": "postToSlack",
            "params": {
                "url": "https://my-incoming-slack-url.com",
                "messagePrefix": "**Blocked Card**",
                "includeDescription": true
            }
        },
        "hasSecrets": false
    }
}



Updated 2023-05-04 @ 07:05 AM