State Machines
Overview
State machines, also known as workflows, are definitions of how tasks behave. They define the initial state, what state they can change to, what triggers are executed, send reminders, and more.
These are just some of the most basic API requests. For a complete list of endpoints, consult our API documentation on Swagger.
Get All State Machines within Group
Returns all state machines that exist within the specified task group.
GET /tasks/{groupId}/sm/smstatemachineEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sm/smstatemachine' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
Responses follow the COTSMStateMachine data model.
Get State Machine by Id
Returns the state machine indicated by its Id.
GET /tasks/{groupId}/sm/smstatemachine/{stateMachineId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine/{stateMachineId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
stateMachineId | The ObjectId of the state machine that is to be returned. | ObjectId<COTSMStateMachine> |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sm/smstatemachine/616eafbda973cd46d72fb841' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
The response follows the COTSMStateMachine data model.
Create New State Machine
Create a new state machine within a task group.
POST /tasks/{groupId}/sm/smstatemachineEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group where the state machine is to be created. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Indicates the body's format. | Required | application/json |
Request Body
Only required fields are listed below. For a complete schema description, please go to the COTSMStateMachine data model. Unrequired fields that are not submitted are either filled in automatically or left blank.
Element | Description | Type | Required | Notes |
---|---|---|---|---|
asset | Indicates the asset the task represents through a property and its property type. | object | Required | |
asset.property | The asset's property (element) ID. | ObjectId<COTProperty> | Required | |
asset.propertyType | The asset's property type (collection) ID. | ObjectId<COTPropertyType> | Required | |
asset.type | Use the generic type for tasks that need to be repeated. Use unique for one-time tasks. | string | Required | Enum: [ "generic", "unique" ] |
code | The state machine's unique identification name. | string | Required | Maximum 60 characters; only lowercase letters, numbers, and underscore allowed; must be unique. |
name | The workflow's display name | string | Required | |
propertyType | Indicates the collection (property type) that contains the elements that represent the workflow's states. | ObjectId<COTPropertyType> | Required |
Request Sample
curl --location --request POST 'https://www.cotalker.com/api/v1/tasks/6179f1b04f04ff1c7f7cf01a/sm/smstatemachine' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"propertyType": "6179f1cb4f1389218162fe05",
"asset": {
"type": "generic",
"propertyType": "6179f1d155753e932b4cb08c",
"property": "6179f1d8a1d9328faf5e2855"
},
"code": "work_order_00",
"name": "Work Order"
}'
Response Sample
Go to COTSMStateMachine for a complete description of the response.
{
"hooks": {
"onCreate": []
},
"requiredSurvey": {
"permissions": [],
"parametrizedBot": []
},
"dynamicPropertyTypes": {
"isActive": []
},
"isActive": true,
"taskChannelType": "unbound-hierarchy",
"allowedExtensions": [],
"_id": "61aa141d45ac56f638e4c75f",
"propertyType": "6179f1cb4f1389218162fe05",
"asset": {
"type": "generic",
"propertyType": "6179f1d155753e932b4cb08c",
"property": "6179f1d8a1d9328faf5e2855"
},
"code": "work_order_00",
"name": "Work Order",
"company": "6179f1ee6ec8b62d2406ec46",
"taskGroup": "6179f1b04f04ff1c7f7cf01a",
"createdAt": "2021-12-03T12:47:05.723Z",
"__v": 0
}
Update State Machine
Updates or edits the indicated state machine.
PATCH /tasks/{groupId}/sm/smstatemachine/{stateMachineId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine/{stateMachineId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
stateMachineId | The ObjectId of the state machine that is to be updated. | ObjectId<COTSMStateMachine> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Sets the body's format. | Required | application/json |
Request Body
Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTSMStateMachine data model.
Request Sample
curl --location --request PATCH 'https://www.cotalker.com/api/v1/tasks/6179f1b04f04ff1c7f7cf01a/sm/smstatemachine/61aa141d45ac56f638e4c75f' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"dynamicPropertyTypes": {
"status1": "61aa196190615805ca094a6d",
"status2": "61aa1969db7d9fbf9992f460",
"status3": "61aa197138404ad7fd09a218",
"status4": null,
"status5": null,
"isActive": [
"status1",
"status2",
"status3"
]
}
}'
Response Sample
Go to COTSMStateMachine for a complete description of the response.
{
"hooks": {
"onCreate": []
},
"requiredSurvey": {
"permissions": [],
"parametrizedBot": []
},
"asset": {
"type": "generic",
"propertyType": "6179f1d155753e932b4cb08c",
"property": "6179f1d8a1d9328faf5e2855"
},
"dynamicPropertyTypes": {
"status1": "61aa196190615805ca094a6d",
"status2": "61aa1969db7d9fbf9992f460",
"status3": "61aa197138404ad7fd09a218",
"status4": null,
"status5": null,
"isActive": [
"status1",
"status2",
"status3"
]
},
"isActive": true,
"taskChannelType": "unbound-hierarchy",
"allowedExtensions": [],
"_id": "61aa141d45ac56f638e4c75f",
"propertyType": "6179f1cb4f1389218162fe05",
"code": "work_order_00",
"name": "Work Order",
"company": "6179f1ee6ec8b62d2406ec46",
"taskGroup": "6179f1b04f04ff1c7f7cf01a",
"createdAt": "2021-12-03T12:47:05.723Z",
"__v": 0
}
Get All States within Group
Returns all the states that exist within the group.
GET /tasks/{groupId}/sm/smstateEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sm/smstate' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
Responses follow the COTSMState data model.
Get All States (extended data)
Returns all the states the exist within the group with more fields and extended data.
GET /tasks/{groupId}/sm/smstate/allEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate/all
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sm/smstate/all' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
Responses follow the COTSMState data model.
Get State Machine by Id
Returns the state indicated by its Id.
GET /tasks/{groupId}/sm/smstate/{stateId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate/{stateId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
stateMachineId | The ObjectId of the state machine that is to be returned. | ObjectId<COTSMState> |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/6179f1b04f04ff1c7f7cf01a/sm/smstate/61aa3f81442b6a4e3a1f7def' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
The response follows the COTSMState data model.
Create New State
Create a new state within a state machine.
POST /tasks/{groupId}/sm/smstateEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group where the state is to be created. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Indicates the body's format. | Required | application/json |
Request Body
Only required fields are listed below. For a complete schema description, please go to the COTSMState data model. Unrequired fields that are not submitted are either filled in automatically or left blank.
Element | Description | Type | Required | Notes |
---|---|---|---|---|
property | The state's property or element ID. | ObjectId<COTProperty> | Required | |
stateMachine | The state machine or workflow the state belongs to. | ObjectId<COTSMStateMachine> | Required |
Request Sample
curl --location --request POST 'https://www.cotalker.com/api/v1/tasks/61aa3f5be1f8a394d17cead9/sm/smstate' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"property": "61aa3fa76b5879d7637a433d",
"stateMachine": "61aa141d45ac56f638e4c75f"
}'
Response Sample
Go to COTSMState for a complete description of the response.
{
"subtask": {
"triggers": []
},
"isActive": true,
"type": "in-progress",
"_id": "61aa3f81442b6a4e3a1f7def",
"property": "61aa3fa76b5879d7637a433d",
"stateMachine": "61aa141d45ac56f638e4c75f",
"company": "61825e70d775394b54bc9801",
"taskGroup": "61aa3f5be1f8a394d17cead9",
"createdAt": "2021-12-03T14:40:37.890Z",
"next": [],
"surveyTriggers": [],
"modifiedAt": "2021-12-03T14:40:37.909Z",
"__v": 0
}
Update State
Updates or edits the indicated state.
PATCH /tasks/{groupId}/sm/smstate/{stateId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate/{stateId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
stateId | The ObjectId of the state that is to be updated. | ObjectId<COTSMState> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Sets the body's format. | Required | application/json |
Request Body
Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTSMState data model.
Request Sample
curl --location --request PATCH 'https://www.cotalker.com/api/v1/tasks/61aa3f5be1f8a394d17cead9/sm/smstate/61aa3f81442b6a4e3a1f7def' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--data-raw '{
"type": "closed"
}'
Response Sample
Go to COTSMState for a complete description of the response.
{
"subtask": {
"triggers": []
},
"isActive": true,
"type": "closed",
"_id": "61aa3f81442b6a4e3a1f7def",
"property": "61aa3fa76b5879d7637a433d",
"stateMachine": "61aa141d45ac56f638e4c75f",
"company": "61825e70d775394b54bc9801",
"taskGroup": "61aa3f5be1f8a394d17cead9",
"createdAt": "2021-12-03T14:40:37.890Z",
"next": [],
"surveyTriggers": [],
"modifiedAt": "2021-12-03T14:47:35.777Z",
"__v": 0
}
Get All SLAs in State Machine
Returns all SLAs found in the indicated state machine.
GET /tasks/{groupId}/sla/smstatemachine/{stateMachineId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sla/smstatemachine/{stateMachineId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
stateMachineId | The ObjectId of the state machine that is to be searched through. | ObjectId<COTSMStateMachine> |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sla/smstatemachine/616eafbda973cd46d72fb841' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
The response follows the COTSMSLA data model.
Get SLA by Id
Returns the SLA indicated by its Id.
GET /tasks/{groupId}/sla/{slaId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sla/smstatemachine/{stateMachineId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
slaId | The ObjectId of the SLA that is to be returned. | ObjectId<COTSMSLA> |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Request Sample
curl --location --request GET 'https://www.cotalker.com/api/v1/tasks/616eafbda973cd46d72fb841/sla/605fa3ace2170f000818ac09' \
--header 'Authorization: Bearer $ACCESS_TOKEN'
Response Sample
The response follows the COTSMSLA data model.
Create SLA
Create a new SLA within a state machine.
POST /tasks/{groupId}/slaEndpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sla
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group where the task is to be created. | ObjectId<COTTaskGroup> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Indicates the body's format. | Required | application/json |
Request Body
Only required fields are listed below. For a complete schema description, please go to the COTSLA data model. Unrequired fields that are not submitted are either filled in automatically or left blank.
Element | Description | Type | Required | Notes |
---|---|---|---|---|
code | The SLA's code name | string | Required | Maximum 60 characters; only lowercase letters, numbers, and underscores allowed; must be unique. |
data | Date and time configuration for the SLA. | object | Required | |
data.time | Specifies the date or time that the task is supposed to go from its initial to final state. | string | Required | Details available here. |
data.timeType | Indicates how time is calculated. Options are dynamic or static . | string | Required | Details available here. |
display | The SLA's display name | string | Required | |
end | Specifies when an SLA should be considered completed. | object | Required | Either states or types can be used to specify SLA completion, but it is not recommended to use both. |
end.states | Specifies the task states in which the SLA is completed. | ObjectId<COTSMStates>[ ] | Required if end.types not used. | |
end.types | Specifies the task types in which the SLA is completed. | string[ ] | Required if end.states not used. | Enum: ["new", "in-progress", "closed"] |
pb | Contains the routine that sets off with the SLA. | COTParametrizedBot | Required | |
start | Specifies when an SLA should initiate. | object | Required | Either states or types can be used to specify SLA initiation, but it is not recommended to use both. |
start.states | Specifies the task states in which the SLA is initialized. | ObjectId<COTSMStates>[ ] | Required if start.types not used. | |
start.types | Specifies the task types in which the SLA is initialized. | string[ ] | Required if start.states not used. | Enum: ["new", "in-progress", "closed"] |
stateMachine | The state machine or workflow the state belongs to. | ObjectId<COTSMStateMachine> | Required |
Request Sample
curl --location --request POST 'https://www.cotalker.com/api/v1/tasks/61827e87b9c09c7f7e121596/sla' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"pb": {},
"data": {
"timeType": "dynamic",
"time": "DATE|endDate"
},
"display": "Customer Support SLA",
"code": "customer_support_sla",
"stateMachine": "61aa0cd673f97ba87978c855",
"start": {
"types": "new"
},
"end": {
"types": "closed"
}
}'
Response Sample
Go to COTSLA for a complete description of the response.
{
"start": {
"types": [
"new"
],
"states": []
},
"end": {
"types": [
"closed"
],
"states": []
},
"data": {
"baseDate": "default",
"timeType": "dynamic",
"time": "DATE|endDate"
},
"isActive": true,
"reset": true,
"repeat": false,
"_id": "61aa0d46224412d597aba341",
"pb": {
"default": {
"stages": []
},
"_id": "61aa0d4dc759a32f408d74a6",
"stages": []
},
"display": "Customer Support SLA",
"code": "customer_support_sla",
"stateMachine": "61827e81855c63e18d38be7a",
"company": "61827e8fb10fe5e98e1438ef",
"taskGroup": "61827e87b9c09c7f7e121596",
"createdAt": "2021-12-03T11:51:41.034Z",
"modifiedAt": "2021-12-03T11:51:41.036Z",
"__v": 0
}
Update SLA
Updates or edits the indicated SLA.
PATCH /tasks/{groupId}/sla/{slaId}Endpoint URL
https://www.cotalker.com/api/v1/tasks/{groupId}/sla/{slaId}
Path Parameters
Parameter | Description | Type | Required | Notes |
---|---|---|---|---|
groupId | The ObjectId of the task group that is to be searched through. | ObjectId<COTTaskGroup> | Required | |
slaId | The ObjectId of the SLA that is to be updated. | ObjectId<COTSLA> | Required |
Headers
Header | Description | Required | Values |
---|---|---|---|
Authorization | Sends your access token to make an API request. Click here to see how to obtain an access token. | Required | Bearer $ACCESS_TOKEN |
Content-Type | Sets the body's format. | Required | application/json |
Request Body
Only the fields that are being updated or added are required to be put into the body. For a complete schema description, please go to the COTSLA data model.
Request Sample
curl --location --request PATCH 'https://www.cotalker.com/api/v1/tasks/61827e87b9c09c7f7e121596/sla/61aa0d46224412d597aba341' \
--header 'Authorization: Bearer $ACCESS_TOKEN' \
--header 'Content-Type: application/json' \
--data-raw '{
"start": {
"states": "61827e102e8b30db66f7ef63"
}
}'
Response Sample
Go to COTSLA for a complete description of the response.
{
"start": {
"states": [
"61827e102e8b30db66f7ef63"
]
},
"end": {
"types": [
"closed"
],
"states": []
},
"data": {
"baseDate": "default",
"timeType": "dynamic",
"time": "DATE|endDate"
},
"isActive": true,
"reset": true,
"repeat": false,
"_id": "61aa0d46224412d597aba341",
"pb": {
"default": {
"stages": []
},
"_id": "61aa0d4dc759a32f408d74a6",
"stages": []
},
"display": "Customer Support SLA",
"code": "customer_support_sla",
"stateMachine": "61827e81855c63e18d38be7a",
"company": "61827e8fb10fe5e98e1438ef",
"taskGroup": "61827e87b9c09c7f7e121596",
"createdAt": "2021-12-03T11:51:41.034Z",
"modifiedAt": "2021-12-03T12:25:21.283Z",
"__v": 0
}