Chapter 11 - E-mail and AI

First draft. This chapter has not been reviewed yet and may contain mistakes. Please read it with that in mind, and tell us about anything that does not match what you see.

On this page11.1 SendEmail 11.2 StartCopilotConversation 11.3 SendCopilotMessage

These three commands reach outside the form: send an e-mail, optionally with the current view in the body or a PDF of any view attached, and hold a conversation with a Microsoft Copilot Studio agent. All three are processed by the Qdabra Forms server, so the outcome (and any error) comes back from the server. Chapter 1 explains the command syntax, dynamic parameter values and where results go; this chapter assumes you know it.

The examples use this main data source:

my:myFields
  my:RequestID
  my:Requester
  my:RequesterEmail
  my:ApproverEmail
  my:Question
  my:Answer              (rich text or text)
  my:ConversationID

11.1 SendEmail

Sends an e-mail message from the form. The body can be text, HTML, the current form view, or a text or HTML introduction followed by the view, and a PDF of any view can be attached. Use it instead of an e-mail data connection when the recipients, subject or attachment are decided at run time.

Syntax

SendEmail /to=<addresses> [/subject=<text>] [/body=<text>] [/bodyishtml=true] [/includeformview=true] [/cc=<addresses>] [/bcc=<addresses>] [/from=<address>] [/attachaspdf=true [/pdffilename=<name>] [/pdfviewname=<view>]]

Parameter	Required	Description
`/to`	Yes	Recipient address(es). Separate several with semicolons.
`/subject`	See Notes	Subject line. Default empty.
`/body`	See Notes	Message body. Plain text unless `/bodyishtml=true`. Default empty.
`/bodyishtml`	No	`true` sends `/body` as HTML. Default `false`.
`/includeformview`	See Notes	`true` renders the current view as HTML and puts it in the message body, after `/body` if one is given. Default `false`.
`/cc`	No	Cc recipient(s), separated by semicolons.
`/bcc`	No	Bcc recipient(s), separated by semicolons.
`/from`	No	Sender address. When omitted, the server's default sender is used (the Command Builder describes it as your tenant's verified sender).
`/attachaspdf`	No	`true` attaches a PDF of a view. Default `false`.
`/pdffilename`	No	With `/attachaspdf=true`: file name of the PDF. Default `Form.pdf`. If the name has no extension, `.pdf` is added.
`/pdfviewname`	No	With `/attachaspdf=true`: the view to render as PDF. Default: the current view.

Result: empty on success. Success is false if the parameters are invalid or the server could not send the message; the server's message is in Error.

Examples

SendEmail /[email protected];[email protected] /subject=Expense report submitted /body=A new expense report is ready for review.
SendEmail /to-xpath=/my:myFields/my:ApproverEmail /cc-xpath=/my:myFields/my:RequesterEmail /subject=Approval needed /body=<p>Please review the request below.</p> /bodyishtml=true /includeformview=true
SendEmail /to-xpath=/my:myFields/my:RequesterEmail /subject=Your request /body=Your request is approved. The approved form is attached. /attachaspdf=true /pdffilename=Request /pdfviewname=Print View

The first sends a plain-text message to two recipients. The second takes the addresses from the form and sends an HTML introduction followed by the current view. The third attaches the Print View view as Request.pdf.

Notes

You must give at least one of /subject, /body or /includeformview=true; otherwise the command fails with At least one of /subject, /body, or /includeformview must be specified.
/pdffilename and /pdfviewname are only valid with /attachaspdf=true. Otherwise the command fails with /pdffilename cannot be specified when /attachaspdf is false. or /pdfviewname cannot be specified when /attachaspdf is false., even when the value is empty.
With /includeformview=true the message is always sent as HTML. A /body is placed above the view, followed by a horizontal line (<hr>); without a /body there is no line. A plain-text body is inserted as text: characters such as < and & appear as typed, and its line breaks are kept. With /bodyishtml=true the body is inserted as HTML.
Images in the included view are sent as inline attachments of the message.
/includeformview always uses the current view. To send a different view, switch to it first, or attach it as a PDF with /pdfviewname.
A file name that already has any extension (for example Report.v2) is used as it is; .pdf is added only when there is none.
The result does not contain any delivery information. Success true means the server accepted the message.
Because a value runs until the next /name=, a body may contain spaces and slashes, but not a space followed by /word=. For long or HTML bodies, build the text in a field and pass it with /body-xpath= (see Chapter 1).

Related: StartCopilotConversation, GetValue.

11.2 StartCopilotConversation

Starts a new conversation with a Microsoft Copilot Studio agent and returns its conversation ID. Run it once, keep the ID, and then send messages with SendCopilotMessage.

Syntax

StartCopilotConversation /environmentid=<environment ID> /schemaname=<agent schema name>

Parameter	Required	Description
`/environmentid`	Yes	The Copilot Studio (Power Platform) environment ID that contains the agent.
`/schemaname`	Yes	The agent's schema name in Copilot Studio.

Result: the conversation ID. Success is false if the server could not start the conversation; the server's message is in Error.

Example

StartCopilotConversation /environmentid=Default-1a2b3c4d-0000-1111-2222-333344445555 /schemaname=cr123_expenseHelper /resultxpath=/my:myFields/my:ConversationID

Starts a conversation with the cr123_expenseHelper agent and stores the conversation ID in ConversationID.

How the two Copilot commands work together

StartCopilotConversation asks the server to open a conversation. The server returns a conversation ID and an access token for that conversation.
qRules keeps the token in the browser's memory, keyed by the conversation ID, and returns only the ID in Result. Store it in a field with /resultxpath (or a Set a field value action).
SendCopilotMessage takes that ID in /conversationid, looks up the matching token, and sends the message with it. Each call continues the same conversation, so the agent keeps its context between messages.

Notes

Every call starts a new, separate conversation. Run it once (for example on a button that opens the chat, or on QdabraRules > finishedLoading) and reuse the ID; do not run it before every message.
The token is not saved with the form. It exists only while the form stays open in the same browser page. A conversation ID saved in the form data cannot be continued after the page is reloaded or the form is opened again later; start a new conversation instead.
There is no command to end a conversation. Starting a new one is enough.

Related: SendCopilotMessage.

11.3 SendCopilotMessage

Sends a message in a conversation started by StartCopilotConversation and returns the agent's reply.

Syntax

SendCopilotMessage /conversationid=<ID> /message=<text> [/responseformat=xml]

Parameter	Required	Description
`/conversationid`	Yes	The conversation ID returned by StartCopilotConversation.
`/message`	Yes	The message to send to the agent.
`/responseformat`	No	How the server formats the reply. When omitted, the agent's Markdown reply is converted to XHTML. `xml` extracts XML from the reply. The value is passed to the server as it is.

Result: the formatted reply, for example <p>Hello!</p> in the default format. Success is false if the conversation ID is unknown, the server call fails, or the agent returns no formatted reply.

Examples

SendCopilotMessage /conversationid-xpath=/my:myFields/my:ConversationID /message-xpath=/my:myFields/my:Question /resultxpath=/my:myFields/my:Answer
SendCopilotMessage /conversationid-xpath=/my:myFields/my:ConversationID /message=Return the expense categories as XML. /responseformat=xml

The first sends the question typed in Question and writes the reply into Answer. The second asks for XML and returns the XML extracted from the reply.

Notes

Pass the ID and the message with -xpath (see Chapter 1). The ID comes from a field, and a question typed by the user may contain quotes, slashes or /word= text that would break a fixed command string.
If the ID was not started in this browser page (for example a saved ID after the form was reopened, or a mistyped ID), the command fails with No active conversation found for the specified conversation ID without contacting the server. Start a new conversation.
If the agent's reply has no formatted content, the command fails with The Copilot agent did not return a formatted response.
Other errors (for example from the server or from Copilot Studio) appear in Error as the server returns them.
The reply in the default format is XHTML markup returned as text.

Related: StartCopilotConversation, SetValue.

Back to the Command Index.

← Files, attachments and images