{import:import:mode}

Description

Starts an import of the slice from a planned task. Write it in the text (or the condition) of a planned task of the slice: when the task runs, the command queues a run of the import given by its id or name and answers with a short code. Outside a running planned task it does nothing and returns an empty string - in a view, on a page, in a step of an import. Inside a task, a call that the task's own text or condition does not write itself - one coming from a view, an included text or an item the task shows - answers imp:invalid and starts nothing. The import must belong to the slice of the task; a task cannot start the import of another slice. A planned task that runs on an event (an item save) gets imp:invalid, because its import would save items and start the task again, for good. The import runs with the rights of the user who saved the task last. The answer is one of: imp:queued (the run is queued), imp:busy (a run of the import is in the way), imp:off (the import is disabled), imp:unknown (the slice has no import of that id or name), imp:invalid (a wrong call, a name two imports of the slice share, a task run on an event, or an import that cannot start - only a shared name and an import that cannot start are logged, once a day) and imp:denied (the task was saved before tasks recorded who saved them, or that user does not manage the feeding of the slice). The answers are short on purpose: the Log keeps only the first 40 bytes of the task name and its output together, and the task list shows the answer as the result of the last run only when it is the whole output of the task - so write the call alone in the task text and keep the task name short.

Parameters

import required

The id (32 hexadecimal characters) or the name of an import of the slice the planned task belongs to. A name is compared regardless of letter case and trailing spaces; when two imports of the slice share the name, the call is invalid. An id of an import of another slice is not found. Write it as plain text in the task: an id or name made by an alias, a define or a nested command is never matched and the call answers imp:invalid.

mode optional default run

What the queued run does. Letter case and surrounding spaces do not matter; an empty value means run. Write it as plain text too - a mode made by an expression answers imp:invalid. Any other value - including baseline, which only a person can start from the import page - makes the call invalid.

Allowed values run - a full run, every stream of the source is imported; changed - only the streams the source reports as changed; check - asks the source whether it works and stores nothing.

Examples

test[{import:prices}]
Expected[]
Actual[]
This page is no planned task, so the command does nothing and returns an empty string - the brackets are literal text that make it visible. The same call in the text of a planned task of the slice queues the import named prices.
test[{import:prices:changed}]
Expected[]
Actual[]
Every mode does nothing outside a planned task, so documentation, views and pages can show the call without starting any import.
virtual{import:prices:changed}
Expected(imp:queued - in the text of a planned task of the slice that has one import named prices)
Illustrative: the answer the task log shows when the task runs. The run imports only the streams the source reports as changed. Other answers: imp:busy when a run is in the way, imp:off for a disabled import, imp:unknown when the slice has no such import.
virtual{import:prices:baseline}
Expected(imp:invalid - in a planned task; baseline is started only by a person on the import page)
Illustrative: a task accepts only run, changed and check. Any other mode, extra parameters, or a call in a task that runs on an item save answers imp:invalid and starts nothing.