|
| 1 | +--- |
| 2 | +description: seatable-html-page-sdk reference for sending notifications and emails, and running configured Python scripts from an HTML page. |
| 3 | +--- |
| 4 | + |
| 5 | +# Actions |
| 6 | + |
| 7 | +Action operations on the `seatable-html-page-sdk`. They start asynchronous notification, email, or Python-script tasks. All methods are asynchronous — `await` them. The `sdk` instance below is created and initialized as shown in [Initialization](initialization.md). |
| 8 | + |
| 9 | +!!! warning "Response format" |
| 10 | + |
| 11 | + Action methods resolve to the underlying HTTP response. Read the payload from `.data`. Methods that start a task return its identifier in `.data.task_id`; retain this ID when the page needs to query task progress or results. |
| 12 | + |
| 13 | +## Notifications and email |
| 14 | + |
| 15 | +!!! abstract "sendNotification" |
| 16 | + |
| 17 | + Create a notification task associated with one row. |
| 18 | + |
| 19 | + ```js |
| 20 | + sdk.sendNotification({ tableName, rowId, emails, msg }); |
| 21 | + ``` |
| 22 | + |
| 23 | + __Parameters__ |
| 24 | + |
| 25 | + `tableName` |
| 26 | + : string — display name of the table containing the row |
| 27 | + |
| 28 | + `rowId` |
| 29 | + : string — `_id` of the row associated with the notification |
| 30 | + |
| 31 | + `emails` |
| 32 | + : array — non-empty list of recipient email addresses |
| 33 | + |
| 34 | + `msg` |
| 35 | + : string — non-empty notification text. It can contain row-value template placeholders such as `{Order number}`. |
| 36 | + |
| 37 | + __Returns__ `.data` holds `{ task_id }` — use `task_id` with `getMessageStatus`. |
| 38 | + |
| 39 | + __Example__ |
| 40 | + ```js |
| 41 | + const res = await sdk.sendNotification({ |
| 42 | + tableName: "Orders", |
| 43 | + rowId: "fcHIocncTsOygA3FjL-toQ", |
| 44 | + emails: ["a7f34c91e2bd4d6b8a50f1c73e9d2a48@auth.local"], |
| 45 | + msg: "Your order {Order number} has been shipped.", |
| 46 | + }); |
| 47 | + const taskId = res.data.task_id; |
| 48 | + ``` |
| 49 | + |
| 50 | +!!! abstract "sendEmail" |
| 51 | + |
| 52 | + Create an email task associated with one row. |
| 53 | + |
| 54 | + ```js |
| 55 | + sdk.sendEmail({ |
| 56 | + tableName, |
| 57 | + rowId, |
| 58 | + accountName, |
| 59 | + sendTo, |
| 60 | + copyTo, |
| 61 | + replyTo, |
| 62 | + subject, |
| 63 | + message, |
| 64 | + htmlMessage, |
| 65 | + attachmentColumnNames, |
| 66 | + }); |
| 67 | + ``` |
| 68 | + |
| 69 | + __Parameters__ |
| 70 | + |
| 71 | + `tableName` |
| 72 | + : string — display name of the table containing the row |
| 73 | + |
| 74 | + `rowId` |
| 75 | + : string — `_id` of the row associated with the email |
| 76 | + |
| 77 | + `accountName` |
| 78 | + : string — name of the configured email account |
| 79 | + |
| 80 | + `sendTo` |
| 81 | + : array — non-empty list of recipient email addresses or row-value templates |
| 82 | + |
| 83 | + `copyTo` |
| 84 | + : array — optional list of CC email addresses or row-value templates |
| 85 | + |
| 86 | + `replyTo` |
| 87 | + : string — optional Reply-To email address or row-value template |
| 88 | + |
| 89 | + `subject` |
| 90 | + : string — non-empty plain-text email subject |
| 91 | + |
| 92 | + `message` |
| 93 | + : string — plain-text body template |
| 94 | + |
| 95 | + `htmlMessage` |
| 96 | + : string — HTML body template |
| 97 | + |
| 98 | + `attachmentColumnNames` |
| 99 | + : array — optional list of FILE column display names; do not use column keys |
| 100 | + |
| 101 | + `message` and `htmlMessage` must provide exactly one body: do not pass both, and do not omit both. Recipient values and the message body can use row-value template placeholders such as `{Customer email}` and `{Order number}`. |
| 102 | + |
| 103 | + __Returns__ `.data` holds `{ task_id }` — use `task_id` with `getMessageStatus`. |
| 104 | + |
| 105 | + __Example__ |
| 106 | + ```js |
| 107 | + const res = await sdk.sendEmail({ |
| 108 | + tableName: "Orders", |
| 109 | + rowId: "fcHIocncTsOygA3FjL-toQ", |
| 110 | + accountName: "Operations SMTP", |
| 111 | + sendTo: ["customer@example.com"], |
| 112 | + copyTo: ["orders-audit@example.com"], |
| 113 | + replyTo: "support@example.com", |
| 114 | + subject: "Order shipment notification", |
| 115 | + htmlMessage: "<p>Your order <strong>{Order number}</strong> has been shipped.</p>", |
| 116 | + attachmentColumnNames: ["Invoice"], |
| 117 | + }); |
| 118 | + const taskId = res.data.task_id; |
| 119 | + ``` |
| 120 | + |
| 121 | +!!! abstract "getMessageStatus" |
| 122 | + |
| 123 | + Get the status of a notification or email task returned by `sendNotification` or `sendEmail`. |
| 124 | + |
| 125 | + ```js |
| 126 | + sdk.getMessageStatus({ taskId }); |
| 127 | + ``` |
| 128 | + |
| 129 | + __Parameters__ |
| 130 | + |
| 131 | + `taskId` |
| 132 | + : string — task identifier returned in `response.data.task_id` |
| 133 | + |
| 134 | + __Example__ |
| 135 | + ```js |
| 136 | + const res = await sdk.getMessageStatus({ taskId }); |
| 137 | + if (res.data.is_finished) { |
| 138 | + // Stop polling and update the UI. |
| 139 | + } |
| 140 | + ``` |
| 141 | + |
| 142 | + Do not query the status until the task-starting method has returned its `task_id`. |
| 143 | + |
| 144 | +## Python scripts |
| 145 | + |
| 146 | +!!! abstract "runScript" |
| 147 | + |
| 148 | + Start a configured Python script. |
| 149 | + |
| 150 | + ```js |
| 151 | + sdk.runScript({ scriptName, tableName, rowId }); |
| 152 | + ``` |
| 153 | + |
| 154 | + __Parameters__ |
| 155 | + |
| 156 | + `scriptName` |
| 157 | + : string — displayed name of the configured script, not its internal ID or file name |
| 158 | + |
| 159 | + `tableName` |
| 160 | + : string — optional display name of the table that supplies the row context |
| 161 | + |
| 162 | + `rowId` |
| 163 | + : string — optional `_id` of the row that supplies the row context |
| 164 | + |
| 165 | + Provide `tableName` and `rowId` together when the script needs a row context, or omit both when it does not. |
| 166 | + |
| 167 | + __Returns__ `.data` holds `{ task_id }` — use `task_id` with `getScriptResult`. |
| 168 | + |
| 169 | + __Example__ |
| 170 | + ```js |
| 171 | + const res = await sdk.runScript({ |
| 172 | + scriptName: "Generate order report", |
| 173 | + tableName: "Orders", |
| 174 | + rowId: "fcHIocncTsOygA3FjL-toQ", |
| 175 | + }); |
| 176 | + const taskId = res.data.task_id; |
| 177 | + ``` |
| 178 | + |
| 179 | +!!! abstract "getScriptResult" |
| 180 | + |
| 181 | + Get the result of a script started by `runScript`. |
| 182 | + |
| 183 | + ```js |
| 184 | + sdk.getScriptResult({ scriptName, taskId }); |
| 185 | + ``` |
| 186 | + |
| 187 | + __Parameters__ |
| 188 | + |
| 189 | + `scriptName` |
| 190 | + : string — the same displayed script name used to start the task |
| 191 | + |
| 192 | + `taskId` |
| 193 | + : string — task identifier returned in `runScript` response `.data.task_id` |
| 194 | + |
| 195 | + __Returns__ `.data` holds `{ script }`. The `script` object includes `state`, `success`, `output`, `return_code`, `started_at`, and `finished_at`. |
| 196 | + |
| 197 | + __Example__ |
| 198 | + ```js |
| 199 | + const res = await sdk.getScriptResult({ |
| 200 | + scriptName: "Generate order report", |
| 201 | + taskId, |
| 202 | + }); |
| 203 | + const scriptResult = res.data.script; |
| 204 | + |
| 205 | + if (scriptResult.state === "finished") { |
| 206 | + if (scriptResult.success) { |
| 207 | + // The script completed successfully. |
| 208 | + } else { |
| 209 | + // Inspect scriptResult.return_code and scriptResult.output. |
| 210 | + } |
| 211 | + } |
| 212 | + ``` |
| 213 | + |
| 214 | + Query the result only with the `taskId` returned by the corresponding `runScript` call. Treat `success: false` or a non-zero `return_code` as a failed execution, and render `output` as plain text rather than HTML. |
0 commit comments