Traditionally, SAS users like their processes to behave like Ron Popeil's famous rotisserie: they want to set it and forget it. That's the definition of a batch process. You work like heck to get it ready to run, then you push the button (or schedule it) and walk away.
But sometimes SAS Enterprise Guide users want their processes to pause while running and wait for some input. It might be just a click to say "okay, keep running now", or it might be to ask a question of the end user. SAS Enterprise Guide has a built-in mechanism for adding prompts, but all of the prompts are gathered and displayed as soon as you begin to run the flow. There isn't a way to display an "in-your-face" message or to prompt at any arbitrary place in the process flow. (Long-time users will remember the %WINDOW macro feature in Base SAS, which can display a window when your program runs. Alas, %WINDOW cannot work with a remote SAS server.)
I built a custom task that allows you to add an interactive message or prompt step to a SAS Enterprise Guide process flow. Unlike a traditional project prompt, this task waits to display a prompt message until the process flow "run time" reaches the point of the Message Prompt task.
You can also tell the task to collect information through a simple prompt. For example: a Yes/No answer, a text value, or a password. In all, the Message Prompt task supports 4 styles of prompts:
- Information message prompt. Displays the text you define, and then continues when the user clicks OK.
- Yes/No question prompt. Displays the text of a question you define and provides Yes/No answer buttons. The response value (YES or NO) is stored in a macro variable named &_MESSAGE_RESULT.
- Text question prompt. Displays the text of a question you define and provides a text field for the user to enter a response. The response is stored in a macro variable named &_PROMPT_VALUE.
- Password question prompt. Displays the text of a question you define and provides a password-style text field for the user to enter a response. The response is stored in a macro variable named &_PASSWORD_VALUE.
Defining Dependencies (or "Run Order")
In order for the task to run and "interrupt" your process flow at precisely the right moment, you must create user-defined links in the flow. These links will establish proper dependencies that ensure that the task runs (and the prompt is displayed) after any prerequisite tasks but before any tasks that need to wait until after the prompt is addressed.
Working with the Task Results
Except for the "Information message" prompt, all prompting styles of the Message Prompt task will yield one or more results that are stored within SAS macro values. The user response (YES/NO/OK/CANCEL) is stored in _MESSAGE_RESULT. The text prompt value is stored in _PROMPT_VALUE or _PASSWORD_VALUE, depending on the style of text prompt that you selected.
You can use these macro variables in subsequent programs or tasks to react accordingly to the user response. You can reference the macro variables in custom programs, and you can also use the macro variables as input to Conditions that you define on tasks within a process flow. (See the SAS Enterprise Guide help documentation for more information about Conditions.)
The Message Prompt task also creates a simple log output that summarizes the task action and the user-supplied values. (In the case of the password prompt, the text value is obscured in the log.)
Using this Task in Scheduled Projects
You should avoid using this task within projects or process flows that you intend to schedule to run unattended. Scheduled projects are run by using the SAS Enterprise Guide automation API, and use of the Message Prompt task in automation will stop the project from running until the prompt is answered.
Download the task
The task is compatible with:
- SAS Enterprise Guide 4.3, 5.1, 6.1 (Windows 32-bit or 64-bit) or later
- SAS 9.2 or later (local install or remote SAS Workspace)
Download: >> SAS.Tasks.MessagePrompt.zip (task and PDF instructions)
(Remember, you might need these unblocking instructions if using version 5.1 or later.)
Thanks a lot, Chris! It's such a luck that I ran across your post - I was struggling just today with the very same problem - to split process flow into pieces for manual intervention. My workaround was to create separate ordered lists for these pieces. But now with this new task any process flow can be really interactive.
Dmitry, I'm glad that you find the task useful! If you have more suggestions for how it should work, post back.
Well, it would be great to make this kind of tasks work similarly to that %WINDOW thing, e.g.:
-to have possibility to insert macrovariables (from previous steps of the process flow) as part of the message.
-to be able to invoke such tasks 'programmatically' - in loops, conditionally etc.
And at the same time to keep 'user-friendliness' of the standard EG prompts, e.g. to support
various types of prompts (calendar, directory/file, date ranges, lists etc.).
It'd be a great addition to SAS EG - it currently seems to be short of interactivity, which prevents from creating a really complex projects, requiring at some points human decisions (data cleaning, e.g.).
Do you think it's possible?
Well, that's what I get for asking!
Actually, I think it would be easy enough to add the macro variables as part of the message. However, the rest of your ideas (programmatically invoke, integrate with "mainstream" prompt styles") would be more difficult. Not impossible, of course -- but probably not something I can get to.
And as I said in the post, I've seen that most users eschew the "interruptions" that would occur while your process is running. They would rather take care of all of those "questions" (especially dealing with data cleansing and the like) up front, as part of the project design. Then when it comes time to repeat the process, just click a button and set it off running. I designed this task to handle the special cases where a mid-process prompt might be needed.
Chris, this task is great. I'm using it for the first time and have some questions. The data I need to verify before continuing the process flow is created just before where I insterted the Message Prompt. But, as soon as the Message Prompt displays, it won't let me out of the pop up to open and verify my data just created. Is there a way around this?
No, I'm afraid not. This task is designed to halt the EG process flow and "block" the application until you answer the prompt and dismiss the message.
If you plan ahead though, you could use this task in combination with the Macro Variable Viewer task. The Macro Variable Viewer does not block the EG application window, you can launch it before you run the flow and leave it visible while your flow runs. When the Message Prompt task runs, you can enter a test in the Macro Variable Viewer "quick expression" check, like:
If this resolves to "1", then the data exists.
I asked our IT to install this DLL....first question:
is this Add-in officially supported by SAS?
It's not part of the shipped product, and hasn't gone through the normal SAS QA/testing process. But this custom task, like many I've shared here, is a very simple, focused feature. We have many customers who use this task with no problems -- it does what it does.
SAS Tech Support will support you in getting this task installed (as well as any custom task we share). If you encounter a problem with the task itself, SAS Tech Support will contact me (the task developer) and I'll investigate and issue a fix if needed. I haven't yet heard of any problems with this particular task, though I sometimes receive feature requests. Those are are "on my list" :)
I want to make my own prompt task. I implemented the ISASTaskExecution interface but it didn't work. When the task runs, no prompt shows up.
Is this sample's source code availble, so I can do some research on it , or can you tell me the point how this task works.
Sorry Chris, It worked!
It seems to be my debug environment problem.
Here's another quitions.
ISASTaskExecution interface has a Cancel methods, and a Run methods. What's difference between them?
Is that possible that I want the process flow be stopped when I select "Cancel" on the prompt.
Sorry again, Chris
I found answer for the question I asked before after I read your book "Custom Tasks for SAS Enterprise Guide" carefully.
I now understand what the Cancel and Run method for, but still have no idea how to implement Cancel. Is there any sample for this out there?
I just published a sample that shows how to cancel a SAS job that your task submits: the Calculate Cardinalities task. But that's a little different than what you're looking for.
Most of my ISASTaskExecution samples don't implement Cancel (returning false). If your process is "interruptable", you can implement what you need to "stop" whatever process you're running. Some caveats: the call to Cancel might come in on a different Windows thread than the one that's actually running the process, so make sure that your "stop processing" code is thread-safe.
I will check the SAS.Tasks.Cardinality sample.
I want to stop the succeeding processes on the flow when user clicked Cancel button on the prompt, since ISASTaskExecution.Run method can return RunStatus.Cancelled, I thought EG will do that for me but nothing happened.
1. What is the RunStatus.Cancelled exact for?
2. Is it possible to tell EG to stop the running process flow, just like stop button is clicked?
RunStatus.Cancelled tells EG to abandon the run of this particular task and return control back to the main application. However, that doesn't affect any downstream tasks in the process flow.
The only way to affect the downstream tasks would be to use a Conditional node around the task, which allows you put something like if-then logic around a node in a process flow. That's not part of the custom task though -- this has to be applied in the project.
Hi, Chris. This looks like a great tool. I want to use it to stop the process to be sure that certain conditions are met before overwriting an existing permanent data set.
I have created two processes: the first reads in the existing permanent data set (DAT1.Master) as a temp file (Temp) and then reads in a monthly update file (Update), with the files then merged (Data Temp2; Set Temp Update;). The second process has a single line of code to overwrite the existing permanent data set (Data DAT1.Master; Set Temp2;). I placed the MessagePrompt task at the beginning of the second process to stop the execution of that code until some output is checked.
However, I can't determine how the OK/Yes/No/Cancel can be used to actually either continue to that step or stop processing the program/cancel out of that step. How would I accomplish that?
You can right-click on the first task of that second process, select Conditions->Add. Then define a Condition that keys off a macro variable. My post here describes the macro variables and values that you can expect. The SAS Enterprise Guide online help (from the Help menu) has a lot of great information about Conditions -- just search the index.
Does this work in SAS EG 7.1 ?
Yes, it should; I've used it there. Let me know if you have issues.
Hi Chris, this is a great Add-In and it helped a lot. I am wondering if it is possible to see the results of a data or print step for a program immediately preceding the Message Prompt? I'm hoping I can inform the Project user of the data before they make a choice in the Message Prompt.
Just realised this was answered above - ignore this post!