Send Actions (Notifications, Webhooks, Emails & AI Nodes)

When setting up a Workflow, you will first need to set up a trigger event to determine when the Action will run. For a list of Trigger Events see our article here: Workflow Trigger Events

This article will focus on Notification Actions. A user can be notified by 3 automated workflow actions. They can receive an E-mail or combined email, and be notified via third-part software integration with a Webhook. 

• Send Notification
• Send Webhook Message
  • Webhook Destination
  • Query Parameter Data
  • Headers Data
  • Body Data
  • Webhook Response Value Expressions
• Send Email
• Send Combined Email
• Send AI Nodes
  • Send Azure OpenAI Classification Node (API Key Required)
  • Send Azure OpenAI Prompt Node (API Key Required)/ Send managed AI Prompt Node (No API Key Required)
  • Send OpenAI Web Search (No API Key Required)
    • Step 1: Perform the Web Search
    • Step 2: Push the Stored Variable into a Field
• Azure OpenAI Privacy Notice

Note: For dynamic reference to Field Labels and Field Descriptions that are most commonly used in AI nodes, there are the expressions fieldLabel() and fieldDescription(). More on these can be found in the expressions article here.

Send Notification

This allows you to send a notification on screen to the user. This is a great tool to give instant feedback of actions to let users know of actions that may have been triggered i.e. if a user triggers and email notification you can add a notification node at the end that says 'Email Sent'.

• Message: This is where you put the message to send to the user
• Target Teams: Here you can choose a team to send the message to
• Target Users: Here you can select a user on the site to send a message to
• Target Person Fields: Here you can select a person field on the app that contains a user you want to send a message to
• Target Current User: Here you can select to send the message to the user who triggered the workflow
• Target Current Users Team: Here you can select to send the message to the users team who triggered the workflow

Note: Another great use for this is to get quick feedback if you having an issue with a workflow not completing but you can't tell where it's failing on the workflow. If you have a chain of 5 nodes for example you can add a notification after each node and before the next stating which node it's after, then when you test in workspace you will see which notification it stops at and then you able to tell which node is failing.

Send Webhook Message

The Send Webhook node enables you to send data (as JSON) outside of the Softools platform. This functionality is commonly used for:

• Transferring data to third-party applications

• Sending notifications to external users (e.g. via Microsoft Teams notifications)

• Triggering external processes often managed with a middle layer such as Microsoft Logic Apps.

For our understanding we will look at a scenario where we would use the send webhook message node. We have a client who uses a third-party software that manages Issues. Softools is used when an Issue needs a deep dive to understand it better and it then sends back the solution to the Third Party issue tracker.

Webhook Destination

The Destination URL is the endpoint to which the webhook message will be sent. This can be found in the third party software and is the API set up to receive the data.

This also needs to be accompanied by the Request Type. The API that has been set up to receive the Webhook message will have a request type set on it based on the action it will perform. These are standards of GET/POST/PATCH/PUT/DELETE.

For our use case we have the following configuration:

• Destination URL: https://thirdpartyissuetracker.net/UpdateIssue - This is the URL of the API expecting a call to update an Issue Record

• Request Type: PATCH - As the expected action of the API called is to update an existing record this would be expected to be PATCH but consult the documentation of the third party system to confirm.

Query Parameter Data

The parameters added here will build up a query string that is appended to the Destination URL. This gives the API that is going to receive the request more information. Commonly it will be which records it needs to peform actions on in it's system. To add Query Parameter:

1. Open the collapsed Query Parameter Data section in the workflow node
2. Set the Key/Value Pairs by either select the appropriate Field or building a custom expression

In our use case for updating an Issue in a third party software this would be to add a commonly shared issued id into the API call. This updates our destination URL to the following structure with the actual Issue ID being pulled dynamically from the [IssueID] Field value in the Record the workflow is triggered on:

New Destination URL - https://thirdpartyissuetracker.net/UpdateIssue?issueid="xxxx-xxx-xxxx"

Headers Data

Headers are additional information that is sent with the Webhook Call. These can be required information such as Authentication, Content-Type or optional information such as the source of the webhook or a feature flag to say whether to use beta functionality on the request.

All calls from the Webhook node will include the following headers:

• Softools-RecordId: the record ID
• Softools-Workflow-RunId: the run ID (as seen in the Workflow Runs view in App Studio)
• Softools-Workflow-NodeId: the node ID (as seen in the Workflow graph editor in App Studio)
• Content-Type: application/json; charset=utf-8

To add Headers:

1. Open the collapsed Header Data section in the workflow node
2. Set the Key/Value Pairs by either select the appropriate Field or building a custom expression

Applying this to our Issue App Workflow scenario, we have added two additional headers. One for Source which means that if there our multiple different systems that our calling the Issue software API then it will know which requests have come from the Softools platform. We also are happy to use the beta functionality offered in the API by setting an additional Header of Feature-Flag to true. 

Body Data

The Body Data is the information that we are going to send as the JSON payload that will be picked up by the API via the destination URL and then used by that API to decide what it needs to do. We have two options on how we send this data:

• Send Full Record - This will send the entire record data to the Destination URL as JSON
• Send Specific Data - Here we choose which values we want to send in the JSON payload by stating those values in Key/Value Pairs via Field selection or built up as expressions.

With our use case for Updating an Issue in a third party system we can see that we do not need to send the whole Record. Instead now that Softools has completed the deep dive of the Issue, it will send back the Issue Resolution which comes dynamically from the [IssueResolution] field value in the Record and a static key/value pair that the status is 'resolved'.

Note: Boolean values from Bit Fields will be sent in the JSON payload as text values of 'True' or 'False'.

Webhook Response Value Expressions

The Webhook Node is sending a request to the Destination URL. Once the Destination URL has picked up the request it is most likely that it will process as per the API of the destination URL and then give a response back. This response back can give data that is relevant to knowing what happened when the request was processed.

We can get at this data using the following references:

• [Meta.ResponseStatusCode] - This is a number which indicates the outcome of the request, telling us whether the request was successful, redirected, resulted in an error, or requires further action.
• [Meta.ResponseHeaders] - It provides metadata about the response (but not the actual content body). Response headers help the client (e.g., browser, API consumer) understand how to handle the response.
• [Meta.ResponseContent] - The response content is the payload we are interested in.

Moreover we can get at specific JSON key values by combining ResponseHeader or ResponseContent with another expression.

•  jsonValue([Meta.ResponseHeaders], 'HeaderKey', 'value if not found') - Returns the value of a specified Header
• jsonValue([Meta.ResponseHeaders], 'ContentKey', 'value if not found') - Returns the value from a key/value pair in the JSON returned in the response payload from the Webhook.

Here we can see how we can use these expressions in a subsequent Update Field Value Node to 

We can apply this to our Issue Resolution use case. When we PATCH the third party Issue Tracker that the Issue Deep Dive in Softools has a resolution, we can listen for the response and take the following information

• Response Code - This lets us know that the request was successful or if there was an problem on the request.
  [Meta.ResponseStatusCode]
• Response Header - We know which Issue we would like to PATCH, if the API we called is set up to return the Record in the other system that is updated, we can use this as a sanity check that our request has been processed correctly.
  jsonvalue([Meta.ResponseHeaders], 'recordId', '')
• Response Content - There could be information that we would like to record in case of need for follow up on the issue. It may be that the API request returns the current Issue Owner's email address. Information like this can be useful to push into the Softools Record following the successful Webhook request.
  jsonvalue([Meta.ResponseContent], 'issueOwner', 'No Owner')

NOTE: Whilst it is good practice, not all APIs are set up to return a response or a response with content so consult the API of the destination URL. GET requests are most likely to have a response with data set back to the User.

Send Email

You can send an email to a User that contains information from the Record that generated the Workflow. Firstly, select 'Notify' as the Action and 'Send Email' as the Result.

Below is example content for sending information about a RAID item that has turned Status Red:

First select 'Notify' as the Action and 'Send Email' as the Result.

To, Cc & Bcc:  The send email feature allows you to target your messages with precision by selecting specific recipients in the To, Cc and Bcc Fields.

You can send emails to specific Users and Teams or you can dynamically send the email to users named in a 'Person', 'Person By Team' or 'Email' Field.

There is also the option in the Bcc to copy in a dynamic Team that is referenced in a 'Team' Field.

To select the relevant users and teams, start typing the name of the user, team or field that references the user, team or email address into the appropriate option and then select as appropriate to build up the recipients.

You can tell if the option you are selecting is a specific user, team or based on a Field value by the icon to the left of the option. In this case Business Unit Team is Field with a team referenced and the other options selected are specific users.

This ensures your communication reaches exactly the right audience, whether it's a single user or a dynamically referenced group.

Email Content: You can then choose if you would like to 'Use Base Template?'. If you select this format then it will format the email to include a Softools header and footer to the body of the message.

You can now set the Subject for the email and the message content. For these you can reference Record data by using @Softools.FieldValue("FieldID") as a Keyword. You can also add a link to the Record that generated the workflow by adding the Keyword @Softools.RecordLink("text shown").  This will create a clickable link to the record if the user clicks the "Text shown" in the email. If you just use the @Softools.RecordLink()without the text to click, then URL will be shown as clickable text

For our example we will use the following in the Subject and Message:

Subject:

@Softools.FieldValue("Title") has turned Status Red

Message:

RAID Item

• A RAID item (@Softools.FieldValue("Title") ) has turned status RED
• Owner : @Softools.FieldValue("Owner_Text")
• Client : @Softools.FieldValue("Client")
• Status: @Softools.FieldValue("Status")
• Tag: @Softools.FieldValue("Tag")
• Due Date : @Softools.FieldValue("DueDate_Formatted")
• Click here to load the record : @Softools.RecordLink()
• @Softools.RecordLinkHtml(click here to show my project) shows an actual URL link with the text provided as the parameter.
• This is the project Description : @Softools.FieldValue("Description")

You can reference Record data by using @Softools.FieldValue("FieldID") as a Keyword.

You can also add a link to the Record that generated the workflow by adding the Keyword @Softools.RecordLink()

Note: For records with multiple forms where you want to attach the record link with the correct form showing (e.g., you have three forms, one for proposal of an idea, one for evaluation of the idea and one for approval and you want to send the record link but open on the approval form), you would use the same Keyword - @Softools.RecordLink() but with a forward-slash and then the form ID like so:

@Softools.RecordLink()/FormID

The message will take a similar syntax to Markdown. Here is an example message for when a support ticket has been completed:

Attachment: Within the email, you can choose to include a Templated Report as an attachment - at the bottom, there is an 'Add Attachment' button allowing you to specify the templated report you wish to attach to the email going out. This needs to be a pre-existing word export template at Record level.

• Alternatively, you can use @Softools.DocumentLink("DocumentFieldID") to put a Document download link directly in the body of the email instead of adding it as an attachment.

Notes: Notes is a handy area for app builders to note down what the purpose of each node is used for to help themselves down the line or for other app builders who work on the app and need some context

• Note:  Attachments are added to emails via a link, this link will last for 30 days.
• Note: The entry for the message is Rich Text. This means that if you copy and paste values in then it will keep the text formatting. This may cause a conflict for the @Softools.FieldValue("Field") references if the text format has changed due to a copy and paste of the Field ID. We recommend that you type the full keyword reference and do not copy and paste values into the Email message to avoid this.
• Note: Some field types are not supported because the emails are rich text and so cannot support more complex field types such as ImageFields, Grids, InAppChart fields... For these, it is better to include them in a Templated Report and attach that.
• Note: Adding a static email address to an email workflow will require you to create an email field in the app with the email as the default value and then reference that field in the workflow as: @Softools.FieldValue("EmialFieldId") otherwise the '@' in the email will try and reference a field that doesn't exist

Following the above example will send an email that looks like this:

Lastly, you will need to say which Users should receive the email. To do this type in the 'To' box and you can search for specific Users and Teams or Users named in Person and Email Fields.

Note: The recipient list must contain one 'To' in order to send the email. If a User is referred to more than once as a result of being selected as a User and a member of a Team and named in a Person or Email Field then they will only receive the email once in priority 'To' then 'Cc' and then 'Bcc'. 

Send Combined Email

This function is similar to the node above with some differences suited for larger amounts of data.

• "Send email" sends one email per record to all the recipients. You can use template substitutions (@Softools.FieldValue... etc) within the subject and message body. The attachments of each email contain only the one record the email is about.
• "Send combined email" sends one email per workflow batch (typically only one email unless the number of records matched is very large) to all the recipients. You cannot use template substitutions (@Softools.FieldValue... etc) within the subject or message body. The attachments are combined reports of all records matched.

Send AI Nodes

Send Azure OpenAI Classification Node

This node allows you to utilise the power of Azure OpenAI for text classification tasks directly within your workflows. This can be used for:

• Automating decision-making based on text inputs.
• Classifying text into predefined categories.
• Enabling smarter workflows using AI-driven insights.

Destination URL: This is the endpoint where your prompt data will be sent. Make sure to use the proper URL of your deployed Azure OpenAI model and include the api-version query parameter.

• Example URL:

  https://api.openai.azure.com/v1/classifications

API Version: Specify the version of the Azure OpenAI API you are targeting. This ensures compatibility between your workflow and the OpenAI model.

• Example:?api-version=2023-06-01

API Key: Enter your Azure OpenAI API key, which is required for authorisation. This ensures that only authenticated requests are processed by the model.

Max Tokens: Set the maximum length of the response in tokens. This defines how much data the AI can generate or classify for a given input.

Temperature: Adjust how "creative" or "focused" the AI responses should be, adjust this setting based on the nature of your classification task:

• Low (0.0–0.4): Focused and deterministic responses.
• High (0.5–1.0): Creative and diverse responses.

Response Variable Name:

You can define a variable name to store the response. This makes it easier to use the results in subsequent workflow steps. This can follow into another node like an email or update field value 

• Example: Var.ClassificationResponse

Classifications: Choose from a list of your select lists for the AI model to classify the text into. The model will choose the best-matched category.

Context Fields: Provide text fields that contain the input data you want to classify. You can include up to 5 fields, enabling flexibility for diverse text classification tasks.

Practical Use Cases

• Sorting customer feedback into categories like "Positive," "Negative," and "Neutral."
• Automating ticket routing based on content (e.g., technical vs. billing issues).
• Classifying emails or text inputs for workflow triggers.

Send Azure OpenAI Prompt Node / Send Managed AI Prompt

These nodes allow you to use the capabilities of Azure OpenAI's chat completion API to generate AI-powered responses directly within your workflows. It is versatile and can be used for tasks such as:

• DATA QUALITY: Address issues of data completeness and quality in legacy systems / Excel
• DOC DATA EXTRACTION: Extract summary data from a linked / uploaded Document
• DATA KEY WORDS & CLUSTERING: Identify common labels for data records to accelerate search and retrieval
• COMPARATIVE ANALYSIS / MATCHING: Identify database records similar to the current record & situation
• DATA CREATION / IDEAS SUGGESTIONS: Generate solutions for common business issues (PromptAI/GenAI)
• SUMMARIES: Create summary reports for Executives based on multiple records

Each use case requires carefully crafted prompts to maximize the relevance, accuracy, and efficiency of the AI model’s responses.

Azure OpenAI Prompt Node vs. Managed AI Prompt Node

The Azure OpenAI Prompt Node allows you to configure the AI node to your own managed AI services and requires an API Key for authorisation with Azure OpenAI. The Managed AI Prompt uses a Softools managed Azure OpenAI deployment. The model is updated for you as newer versions become available; it currently targets GPT 5 Chat.

Azure OpenAI Prompt Node Properties

If you are using your own services to run the Azure OpenAI Prompt Node then you will need to complete the following properties on the workflow node. If you are using the Managed AI Prompt Node then this infrastructure details are handled and inbuilt by Softools so not needed.

Destination URL: This is the endpoint where your prompt data will be sent. Ensure the URL corresponds to your deployed Azure OpenAI model and includes the api-version query parameter.

• Example URL: https://api.openai.azure.com/v1/completions

API Version: Specify the version of the Azure OpenAI API being targeted. This ensures the model responds appropriately.

• Example: ?api-version=2023-06-01

API Key: Enter your Azure OpenAI API key. This is required for authentication to ensure only authorised requests are processed.

Temperature: Adjust the randomness and creativity of the AI's output:

• Low (0.0–0.4): More focused and predictable responses.
• High (0.5–1.0): Creative and varied responses.

Azure OpenAI & Managed AI Prompt Node Properties

The remaining properties will be in both the Managed and Self-Managed versions of the AI Prompt node.

Response Variable Name: Define a variable name to store the AI's response for use in subsequent workflow steps, such as email generation or updating field values.

• Example: Var.PromptResponse

Max Tokens: Set the maximum number of tokens for the AI’s response. This limits the length of the output.

Message Structure: Messages are used to structure the conversation for the Azure OpenAI chat completion API. Each message includes a role and content:

• Roles:
  • system: Defines the AI assistant’s behavior.
  • user: Provides input from the user. This is usually dynamically referenced via expression to a text Field as the user inputs different information each time to get a response.
  • assistant: Represents the AI’s responses.
• Example Message:
  • System: "You are a risk advisor."
  • User: "I'm starting a project creating an application to track our projects"
  • Assistant: "Lay out the risks with a score of 1-5 for severity and likelihood"

Practical Use Cases

• Generating natural language summaries from text fields.
• Providing dynamic and tailored responses to customer queries.
• Drafting email content or report text based on workflow data.

Send OpenAI Web Search

This node is a powerful way of gaining AI insights into Business Process by searching the Web and returning a summary which also includes the websites that have been cited for the information. This node is simpler to configure than the Azure Open AI Prompts and it also does not require an API Key so you are able to harness the power of AI without the need for managed services to run the AI

This is a very versatile function which means the use cases are limitless but lets look at a few.

• Finding Innovative Solutions to items raised in an Issue Log
• Performing Competitor Analysis for a Product Procurement process
• Defining Business Strategy based on Performance in a KPI Scorecard App

Configuration takes 2 steps. The first performs the Web Search and pulls back a summary. This is then stored as a variable in the workflow so it then needs a second action to push that summary value into a Field in the Record.

Step 1: Perform the Web Search

The Web Search needs the Search Query that we want to use. The idea here is to try and be specific with your prompt by adding as much context from the Record as we can. This then gets stored in a variable.

In our example above we are using the use case where we have an Asset Register and each Asset has quarterly inspections. The inspector will write his recommendations in his report but we want a quick way to summarise this and gain insight from a web search to make these into confirmed actionable items.

Response Variable Name: The Response Variable needs a reference which in this case is 'Response' we can then call this later on using [Var.Response] to use the value returned from the search into a new node.

Search Query As Expression: The search query is what we are asking the Web. The more specific we can be the better quality response we will get. Using our example, we could have searched for [InspectionRecommendations] 

This is very limited in accuracy so we can ask the format we want the response to be in such as the 5 best actions to take

'Give me the 5 best actions based on: ' + [InspectionRecommendations]

This is better but if we really want to refine our search we can add some context such as the location of our company and company size. This will mean the response is far better targeted to what we want out of the search.

'Give me the 5 best actions based on: ' + [InspectionRecommendations] + '. Factor in that the company location is ' + [Location] + ' and company size is ' + string([NumberOfEmployees]) + ' employees.'

Notes: Notes do not have any effect on the functionality of the node but they are useful to remind yourself why this workflow node has been used or list any limitations or planned future improvements. It is particularly of value when collaborating on the build with other App Builders.

Once configures, click on OK to add and confirm edits to the node.

Step 2: Push the Stored Variable into a Field

We now choose what we want to do with our new found AI insight. The simplest choice is to place the value back into the Record in a new Field.

Continuing our use case, we have performed a web search based on out Inspectors Recommendations and now have a variable that is storing the response.

We can reference this variable into a Field Update by using the expression [Var.Response] with the variable name in place of 'Response'.

For more on creating records and updating field values see these workflow nodes here.

Here is a sample response for a simple use case of what to do given the recommendation to replace the office coffee machine. You can see that where appropriate websites references have been cited.

Azure OpenAI Privacy Notice

See the Microsoft support article for assurance on data privacy when using AI prompts through Microsoft Azure OpenAI services.

https://learn.microsoft.com/en-us/legal/cognitive-services/openai/data-privacy?tabs=azure-portal

The key points are that

Your prompts (inputs) and completions (outputs), your embeddings, and your training data:

• are NOT available to other customers.
• are NOT available to OpenAI.
• are NOT used to improve OpenAI models.
• are NOT used to train, retrain, or improve Azure OpenAI Service foundation models.
• are NOT used to improve any Microsoft or 3rd party products or services without your permission or instruction.

The Azure OpenAI Service is operated by Microsoft as an Azure service; Microsoft hosts the OpenAI models in Microsoft's Azure environment and the Service does NOT interact with the OpenAI API, which is what Softools uses to provide AI services through Microsoft Azure