Skip to main content

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.

additional resources

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/smstatemachine

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
stateMachineIdThe ObjectId of the state machine that is to be returned.ObjectId<COTSMStateMachine>

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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/smstatemachine

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstatemachine

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group where the state machine is to be created.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeIndicates the body's format.Requiredapplication/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.

ElementDescriptionTypeRequiredNotes
assetIndicates the asset the task represents through a property and its property type.objectRequired
asset.propertyThe asset's property (element) ID.ObjectId<COTProperty> Required
asset.propertyTypeThe asset's property type (collection) ID.ObjectId<COTPropertyType>Required
asset.typeUse the generic type for tasks that need to be repeated. Use unique for one-time tasks.stringRequiredEnum: [ "generic", "unique" ]
codeThe state machine's unique identification name.stringRequiredMaximum 60 characters; only lowercase letters, numbers, and underscore allowed; must be unique.
nameThe workflow's display namestringRequired
propertyTypeIndicates 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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
stateMachineIdThe ObjectId of the state machine that is to be updated.ObjectId<COTSMStateMachine>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeSets the body's format.Requiredapplication/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/smstate

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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/all

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate/all

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
stateMachineIdThe ObjectId of the state machine that is to be returned.ObjectId<COTSMState>

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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/smstate

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sm/smstate

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group where the state is to be created.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeIndicates the body's format.Requiredapplication/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.

ElementDescriptionTypeRequiredNotes
propertyThe state's property or element ID.ObjectId<COTProperty>Required
stateMachineThe 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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
stateIdThe ObjectId of the state that is to be updated.ObjectId<COTSMState>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeSets the body's format.Requiredapplication/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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
stateMachineIdThe ObjectId of the state machine that is to be searched through.ObjectId<COTSMStateMachine>

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
slaIdThe ObjectId of the SLA that is to be returned.ObjectId<COTSMSLA>

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $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}/sla

Endpoint URL

https://www.cotalker.com/api/v1/tasks/{groupId}/sla

Path Parameters

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group where the task is to be created.ObjectId<COTTaskGroup>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeIndicates the body's format.Requiredapplication/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.

ElementDescriptionTypeRequiredNotes
codeThe SLA's code namestringRequiredMaximum 60 characters; only lowercase letters, numbers, and underscores allowed; must be unique.
dataDate and time configuration for the SLA.objectRequired
data.timeSpecifies the date or time that the task is supposed to go from its initial to final state.stringRequiredDetails available here.
data.timeTypeIndicates how time is calculated. Options are dynamic or static.stringRequiredDetails available here.
displayThe SLA's display namestringRequired
endSpecifies when an SLA should be considered completed.objectRequiredEither states or types can be used to specify SLA completion, but it is not recommended to use both.
end.statesSpecifies the task states in which the SLA is completed.ObjectId<COTSMStates>[ ]Required if end.types not used.
end.typesSpecifies the task types in which the SLA is completed.string[ ]Required if end.states not used.Enum: ["new", "in-progress", "closed"]
pbContains the routine that sets off with the SLA.COTParametrizedBotRequired
startSpecifies when an SLA should initiate.objectRequiredEither states or types can be used to specify SLA initiation, but it is not recommended to use both.
start.statesSpecifies the task states in which the SLA is initialized.ObjectId<COTSMStates>[ ]Required if start.types not used.
start.typesSpecifies the task types in which the SLA is initialized.string[ ]Required if start.states not used.Enum: ["new", "in-progress", "closed"]
stateMachineThe 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

ParameterDescriptionTypeRequiredNotes
groupIdThe ObjectId of the task group that is to be searched through.ObjectId<COTTaskGroup>Required
slaIdThe ObjectId of the SLA that is to be updated.ObjectId<COTSLA>Required

Headers

HeaderDescriptionRequiredValues
AuthorizationSends your access token to make an API request.
Click here to see how to obtain an access token.
RequiredBearer $ACCESS_TOKEN
Content-TypeSets the body's format.Requiredapplication/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
}