--- title: "DocumentGenerator" language: "en" type: "Symbol" summary: "DocumentGenerator[template, timespec] represents a document generator with template template to be evaluated on the schedule defined by timespec. DocumentGenerator[template, driver, timespec] takes parameters for filling the template from driver." keywords: - crontab - cron canonical_url: "https://reference.wolfram.com/language/ref/DocumentGenerator.html" source: "Wolfram Language Documentation" related_guides: - title: "Automated Reports" link: "https://reference.wolfram.com/language/guide/AutomatedReports.en.md" - title: "Background & Scheduled Tasks" link: "https://reference.wolfram.com/language/guide/BackgroundAndScheduledTasks.en.md" related_functions: - title: "AutoRefreshed" link: "https://reference.wolfram.com/language/ref/AutoRefreshed.en.md" - title: "Delayed" link: "https://reference.wolfram.com/language/ref/Delayed.en.md" - title: "ScheduledTask" link: "https://reference.wolfram.com/language/ref/ScheduledTask.en.md" - title: "CloudSubmit" link: "https://reference.wolfram.com/language/ref/CloudSubmit.en.md" - title: "TaskSuspend" link: "https://reference.wolfram.com/language/ref/TaskSuspend.en.md" - title: "TaskExecute" link: "https://reference.wolfram.com/language/ref/TaskExecute.en.md" - title: "TaskRemove" link: "https://reference.wolfram.com/language/ref/TaskRemove.en.md" - title: "DocumentGenerators" link: "https://reference.wolfram.com/language/ref/DocumentGenerators.en.md" - title: "DocumentGeneratorInformation" link: "https://reference.wolfram.com/language/ref/DocumentGeneratorInformation.en.md" --- # DocumentGenerator DocumentGenerator[template, timespec] represents a document generator with template template to be evaluated on the schedule defined by timespec. DocumentGenerator[template, driver, timespec] takes parameters for filling the template from driver. ## Details and Options * ``CloudDeploy[DocumentGenerator[…]]`` sets up a document generator in the cloud. The generator periodically applies ``template``, logs the results of the generation process, archives the generated document, and delivers it to any specified recipients. * Document generators can be controlled using functions applicable to scheduled tasks, like ``TaskSuspend`` and ``TaskResume``. ``timespec`` follows the ``ScheduledTask`` specification and may be ``None``. * The argument template can be a ``TemplateObject``, notebook or template notebook, or a specification of the form ``File[…]`` or ``CloudObject[…]`` that contains any of these constructs. * The argument ``driver`` can be an ``Association``, a pure function or a Wolfram Language script evaluating to an ``Association``, a notebook setting the value of ``$CurrentBinding``, or a ``CloudObject`` or ``File`` that contains any of these constructs. * If ``template`` contains template elements, the elements are filled from ``driver``, or from template defaults if ``driver`` is not present. * Cloud objects and files are copied and bundled with the generator when the generator is deployed, unless the specified resources are qualified as ``Delayed``. ``Delayed`` resources are used in place. * The following options can be given: | | | | | ---------------------- | ------------ | -------------------------------------------- | | AutoRemove | False | remove generator after last scheduled run | | DeliveryFunction | None | how to deliver the generated document | | EpilogFunction | None | function evaluated after document generation | | GeneratorDescription | None | textual description of the generator | | GeneratorHistoryLength | 3 | number of generated documents to archive | | GeneratorOutputType | "StaticPage" | type of document to generate | | NotificationFunction | Automatic | how to provide status notifications | | Permissions | Automatic | permissions settings for generated documents | | TimeZone | Automatic | time zone for scheduling | * ``EpilogFunction`` may be a pure function, notebook, ``CloudObject``, or ``File``. * Common settings for ``GeneratorOutputType`` include: | | | | ------------ | ---------------------------- | | "StaticPage" | deployed web page | | "CDF" | notebook served for download | | "PDF" | PDF document | | "CloudCDF" | cloud notebook | * Note that the choice of output type places no restriction on delivery formats specified in ``DeliveryFunction``. * In the cloud, the precise times at which documents are generated are typically determined by load-balancing requirements. * The minimum time between generator executions in the cloud is determined by cloud configuration and policies, and will typically be a certain fraction of an hour. ## Examples (8) ### Basic Examples (2) Create a basic document generator: ```wl In[1]:= co = CloudDeploy[DocumentGenerator[File["ExampleData/BasicTemplate.nb"], None]] Out[1]= CloudObject["https://www.wolframcloud.com/obj/53ce82c9-3292-4958-85e0-6c3986d87769"] ``` Trigger the generator to run asynchronously using ``TaskExecute`` : ```wl In[2]:= TaskExecute[co] Out[2]= CloudObject["https://www.wolframcloud.com/obj/53ce82c9-3292-4958-85e0-6c3986d87769"] ``` Delete the generator: ```wl In[3]:= TaskRemove[co] Out[3]= CloudObject["https://www.wolframcloud.com/obj/53ce82c9-3292-4958-85e0-6c3986d87769"] ``` --- Create a parameterized document generator: ```wl In[1]:= co = With[{template = StringTemplate["Time: `time` Current temperature: `temp`"], driver = <|"time" :> Now, "temp" :> AirTemperatureData[]|>}, CloudDeploy[DocumentGenerator[template, driver, "Hourly"]] ] Out[1]= CloudObject["https://www.wolframcloud.com/obj/2c375031-e535-486c-95a8-1ebd86267643"] ``` Trigger the generator to run asynchronously: ```wl In[2]:= TaskExecute[co] Out[2]= CloudObject["https://www.wolframcloud.com/obj/2c375031-e535-486c-95a8-1ebd86267643"] ``` Delete the generator: ```wl In[3]:= TaskRemove[co] Out[3]= CloudObject["https://www.wolframcloud.com/obj/2c375031-e535-486c-95a8-1ebd86267643"] ``` ### Generalizations & Extensions (1) Use scheduled task functions to control document generator scheduling and execution: ```wl In[1]:= obj = CloudDeploy[DocumentGenerator[File["ExampleData/BasicTemplate.nb"], "Daily"]] Out[1]= CloudObject["https://www.wolframcloud.com/obj/2892aa7d-0db2-4f97-9f45-a917d2eb7856"] ``` Halt scheduled executions: ```wl In[2]:= TaskSuspend[obj] Out[2]= CloudObject["https://www.wolframcloud.com/obj/2892aa7d-0db2-4f97-9f45-a917d2eb7856"] ``` Resume scheduled executions: ```wl In[3]:= TaskResume[obj] Out[3]= CloudObject["https://www.wolframcloud.com/obj/2892aa7d-0db2-4f97-9f45-a917d2eb7856"] ``` Delete the generator: ```wl In[4]:= TaskRemove[obj] Out[4]= CloudObject["https://www.wolframcloud.com/obj/2892aa7d-0db2-4f97-9f45-a917d2eb7856"] ``` ### Options (2) #### DeliveryFunction (1) Deploy a generator that emails its creator a PDF of the generated document: ```wl In[1]:= co = CloudDeploy[DocumentGenerator[File["ExampleData/BasicTemplate.nb"], <|"author" -> $CloudUserID|>, "Daily", DeliveryFunction -> "PDF" ]] Out[1]= CloudObject["https://www.wolframcloud.com/obj/76064240-a337-4e10-9057-a5c90b8ff3e3"] ``` Trigger the generator to run asynchronously: ```wl In[2]:= TaskExecute[co] Out[2]= CloudObject["https://www.wolframcloud.com/obj/76064240-a337-4e10-9057-a5c90b8ff3e3"] ``` Delete the generator: ```wl In[3]:= TaskRemove[co] Out[3]= CloudObject["https://www.wolframcloud.com/obj/76064240-a337-4e10-9057-a5c90b8ff3e3"] ``` #### NotificationFunction (1) Notifications allow indicated parties to receive status messages on task evaluation. Deploy a generator that notifies multiple parties, but has no recipients: ```wl In[1]:= co1 = CloudDeploy[DocumentGenerator[File["ExampleData/BasicTemplate.nb"], <|"author" -> $CloudUserID|>, "Daily", NotificationFunction -> {{$CloudUserID, "a@b.com"} -> All} ]] Out[1]= CloudObject["https://www.wolframcloud.com/obj/4ad5f498-f3e9-4b03-bb56-67e54c49a157"] ``` Trigger the generator to run asynchronously: ```wl In[2]:= TaskExecute[co1] Out[2]= CloudObject["https://www.wolframcloud.com/obj/4ad5f498-f3e9-4b03-bb56-67e54c49a157"] ``` Delete the generator: ```wl In[3]:= TaskRemove[{co1}] Out[3]= {CloudObject["https://www.wolframcloud.com/obj/4ad5f498-f3e9-4b03-bb56-67e54c49a157"]} ``` ### Applications (1) Create a daily report of quiz scores. Simulate scores by sampling them from a ``NormalDistribution`` : ```wl In[1]:= quizScore[μ_, σ_] := Min[Round@RandomVariate[NormalDistribution[μ, σ]], 100]; quizScore["science"] := quizScore[75, 8];quizScore["english"] := quizScore[82, 6];quizScore["maths"] := quizScore[70, 13]; ``` Deploy a generator that evaluates three times a week at 17:00 and compiles a report on the day's scores: ```wl In[2]:= driver = Block[ {names = {"John Smith", "Sarah Cook", "Sam Jones"}, subjects = {"science", "english", "maths"}, raw}, raw = Table[Prepend[(quizScore[#1]&) /@ subjects, n], {n, names}];Association["people" -> (AssociationThread[Prepend[subjects, "name"] -> #1]& /@ raw)] ]&; co = CloudDeploy[DocumentGenerator[ File["ExampleData/RepeatingTemplate.nb"], driver, DateObject[{_, _, Monday | Wednesday | Friday, 17}] ]] Out[2]= CloudObject["https://www.wolframcloud.com/obj/10b791d0-86bb-4a63-9743-487c4e0b9fe1"] ``` Trigger the generator to run synchronously: ```wl In[3]:= TaskExecute[co] Out[3]= CloudObject["https://www.wolframcloud.com/obj/10b791d0-86bb-4a63-9743-487c4e0b9fe1"] ``` Delete the generator: ```wl In[4]:= TaskRemove[co] Out[4]= CloudObject["https://www.wolframcloud.com/obj/10b791d0-86bb-4a63-9743-487c4e0b9fe1"] ``` ### Possible Issues (1) Qualifying a local ``File`` resource as ``Delayed`` results in a deployment error, since the resource will not be available in the cloud at evaluation time: ```wl In[1]:= co = With[{template = Delayed[File["ExampleData/BasicTemplate.nb"]]}, CloudDeploy[DocumentGenerator[template, None]] ] ``` DocumentGenerator::badarg: Bad value File[ExampleData/BasicTemplate.nb] for argument template. ```wl Out[1]= $Failed ``` ### Neat Examples (1) Create a document generator that produces a daily report on the performance over the past $m$ days of the $n$ trucking industry stocks with the highest trading volumes on the previous day: ```wl In[1]:= driver[m_Integer, n_Integer] := Block[{members, reportOn}, members = FinancialData["Trucking", "Members"]; reportOn = Take[Reverse[SortBy[ ({#, Quiet[FinancialData[#, "Volume", {Yesterday}]]}& /@ members) /. {{_, _Missing | _FinancialData} -> Sequence[], {t_String, {{_List, i_Integer}}} :> {t, i}}, Last ]], n][[All, 1]]; <| "Start" :> DateString[DatePlus[Today, -m], "DateShort"], "Stocks" -> ( <|"Name" -> FinancialData[#, "Company"], "Ticker" -> #|>& /@ reportOn) |> ]&; co = CloudDeploy[DocumentGenerator[ File["ExampleData/StocksTemplate.nb"], driver[30, 5], DateObject[{_, _, Tuesday | Wednesday | Thursday | Friday | Saturday, 1}], GeneratorOutputType -> "CloudCDF" ], "trucking-example"] Out[1]= CloudObject[ "https://www.wolframcloud.com/obj/user-e24509c3-9e1f-4ad9-aaa3-60823017ea9e/trucking-example"] ``` The generation time for this report will typically exceed the time limit for synchronous evaluations. Trigger the generator to run asynchronously: ```wl In[2]:= TaskExecute[co] Out[2]= CloudObject[ "https://www.wolframcloud.com/obj/user-e24509c3-9e1f-4ad9-aaa3-60823017ea9e/trucking-example"] ``` Once the report is completed, output may be viewed at this cloud object: ```wl In[3]:= DocumentGeneratorInformation[co, "CurrentOutput"] Out[3]= CloudObject["https://www.wolframcloud.com/obj/55cd787d-4d12-4bcd-af2e-d3aed84b301c"] ``` Delete the generator: ```wl In[4]:= TaskRemove[co] Out[4]= CloudObject[ "https://www.wolframcloud.com/obj/user-e24509c3-9e1f-4ad9-aaa3-60823017ea9e/trucking-example"] ``` ## See Also * [`AutoRefreshed`](https://reference.wolfram.com/language/ref/AutoRefreshed.en.md) * [`Delayed`](https://reference.wolfram.com/language/ref/Delayed.en.md) * [`ScheduledTask`](https://reference.wolfram.com/language/ref/ScheduledTask.en.md) * [`CloudSubmit`](https://reference.wolfram.com/language/ref/CloudSubmit.en.md) * [`TaskSuspend`](https://reference.wolfram.com/language/ref/TaskSuspend.en.md) * [`TaskExecute`](https://reference.wolfram.com/language/ref/TaskExecute.en.md) * [`TaskRemove`](https://reference.wolfram.com/language/ref/TaskRemove.en.md) * [`DocumentGenerators`](https://reference.wolfram.com/language/ref/DocumentGenerators.en.md) * [`DocumentGeneratorInformation`](https://reference.wolfram.com/language/ref/DocumentGeneratorInformation.en.md) ## Related Guides * [Automated Reports](https://reference.wolfram.com/language/guide/AutomatedReports.en.md) * [Background & Scheduled Tasks](https://reference.wolfram.com/language/guide/BackgroundAndScheduledTasks.en.md) ## History * [Introduced in 2014 (10.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn100.en.md) \| [Updated in 2017 (11.2)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn112.en.md)