Create a runbook
Writes a new runbook for the company. The script is the only thing you must supply — leave out the title or description and MagicDoor writes them by reading the script. Requires the maintenance_runbooks:write permission.
Authorization
AuthorizationstringrequiredBody
application/json
scriptstringrequiredThe instructions MagicDoor should follow, in plain English. At least 50 characters.
titlestringThe runbook's name. At most 150 characters. Leave it out to have MagicDoor write one from the script.
descriptionstringWhat the runbook is for. At most 250 characters. Leave it out to have MagicDoor write one from the script.
defaultVendorIdstringThe vendor the runbook should send work to when nothing more specific applies. It must be one of the company's vendors.
defaultPropertyManagerIdstringThe property manager the runbook should hand requests to when nothing more specific applies. They must belong to the company.
Response
200 · The runbook that was created.
publicRunBookbooleanrequiredtrue when MagicDoor supplies this runbook to every company. A shared runbook can be switched on and configured for your company, but its title, description and script cannot be edited or deleted.
idstringrequiredThe runbook.
titlestringrequiredThe runbook's name. MagicDoor writes one from the script when you do not supply it.
descriptionstringrequiredWhat the runbook is for. MagicDoor writes one from the script when you do not supply it.
createdstring · date-timerequiredWhen the runbook was created, in the company's timezone and without an offset.
updatedstring · date-timeWhen the runbook was last changed, in the company's timezone and without an offset.
defaultVendorIdstringThe vendor this runbook sends work to when nothing more specific applies. Absent when none is set.
defaultPropertyManagerIdstringThe property manager this runbook hands requests to when nothing more specific applies. Absent when none is set.
enabledbooleanrequiredWhether the runbook is allowed to pick up this company's maintenance requests. A runbook your company has never configured reads as enabled.
usageCountintegerrequiredHow many times this runbook has been used for this company.
lastUsedstring · date-timeWhen it was last used, in the company's timezone and without an offset. Absent when it has never run.
vendorIdstringdeprecatedA copy of defaultVendorId. Read defaultVendorId instead.
scriptstringrequiredThe instructions MagicDoor follows when the runbook handles a request, in plain English.
lastUseMaintenanceRequestIdstringThe last maintenance request this runbook handled for the company. Absent when it has never run.
vendorOverwritesobject[]requiredPer-portfolio or per-property vendor overrides. An empty array when there are none.
propertyManagerOverwritesobject[]requiredPer-portfolio or per-property property manager overrides. An empty array when there are none.
actionExitCountsobjectrequiredHow many times the runbook has finished each way, as a map. The keys are askQuestion, closeRequest, createWorkOrder, handOverToHuman and reselectRunBook; only the ways it has actually finished appear. An empty object when it has never run.
lastUseMaintenanceRequestobjectThe last maintenance request this runbook handled, in the short row shape used by the maintenance request list. Absent when it has never run, or when that request no longer exists.
400 · The script is shorter than 50 characters, or the title or description is longer than allowed.
401 · The request carried no valid access token.
403 · The token is not a property manager token, or it lacks the `maintenance_runbooks:write` permission.
404 · `defaultVendorId` or `defaultPropertyManagerId` names someone who does not exist, or who belongs to another company.
If MagicDoor has to write the title or description for you and cannot make sense of the script, the runbook is created disabled. Check enabled on the response, and call Enable a runbook once the script reads properly.