Share this article
Don’t know what page scripting tool in BC is? Or maybe you’ve heard about it, but you’re not sure what it’s for? Or perhaps you’ve even seen this feature in action, but you don’t know how to apply it to your daily work?
In this article, I’ll cover few use cases for this fantastic tool and try to inspire you to add page scripting to your suite of favorite Business Central tools. However, I will not cover step-by-step guide with instructions of how to use the tool here – an instructive “how-to” guide may appear on the blog soon, but for now I refer you to the official documentation.
Page scripting tool in the official BC documentation: Use page scripting tool for acceptance testing (preview) ↗. It’s also worth checking out the tool announcement on the documentation pages for the 2024 release wave 1: Use in-client page scripting tool for acceptance testing ↗.
This functionality is in the preview
At the time of writing this article, the page scripting tool is available in a preview version. This means that both the functionality itself and the related documentation may change. I will do my best to monitor this and keep you updated on any changes.
Introduction
Page scripting tool was announced for the 2024 release wave 1 and released with major version 24 in a preview version of the functionality. It can be used for recording actions performed on pages in the Business Central application, and then allows for the playback of such recordings. The principle of operation may resemble the recording and playback of macros in Excel.
Recordings in BC are in script form and can be saved to a file in YAML language format. We can send this file to another person, allowing them to play it back on their own environment and see step-by-step how we progress on a specific process in the application and replicate it themselves. During or after the recording, we can modify and condition each step of the script. We can also add steps to verify if the result (e.g., the value of a given field) meets the expectations.
These functional features create very interesting usage opportunities for both consultants and superusers.
In the hands of a consultant
In the hands of a consultant, page scripting can be a truly powerful tool that supports him in creating project documentation and elevating it to completely new level. It enables the creation of automated test scenarios but also simplifies the creation of traditional ones. It aids in generating documentation or user manuals. Additionally, it allows for the creation of interactive tutorials or scripts for frequently repeated sequences of actions.
In the hands of a superuser
So-called superusers and administrators on the client side can use the tool to create their own test scenarios (for instance, if the Partner hasn’t provided any — shame on them!), or scenarios for extreme edge cases to better (and in an organized way) test all changes delivered to them for testing. Additionally, for this group of users, there is one particular use case for the page scripting tool. This is the capability to create a script with steps to reproduce an encountered error in the system.
And now, let’s take a closer look at each of the above-mentioned use cases for the page scripting tool…
Creating test scenarios
Creating automated test scenarios for changes within PTE is probably the most frequently cited use case for page scripting tool, and it’s likely that the idea of supporting the creation (and execution) of test scenarios was foremost in Microsoft’s mind when developing this functionality.
Record a test scenario
After completing the programming stage and internal tests for the changes prepared for the client, as a consultants, we can use a tool to record all the steps in BC for the process of prepared functionality. This way, we create a script for the first, basic test scenario, which we save to a YAML file (after properly describing it).
Additional test scenarios for process variations
If we need more variants of test scenarios to test a particular function, we can duplicate the saved script, remove some steps from the copy, and re-record some actions in their place, modifying them as necessary to create a script for the next test scenario. We can also change the values specified in the script such as quantities, amounts, or other field values to create scripts for different edge cases. Each variant is saved to a separate YAML file (remember to properly describe each script).
We can optionally edit the saved files further in any text editor (the YAML language format is quite clear and easy to edit) – this way, we can also create different variants of a given script. Sometimes, changing certain properties by editing the file will be faster than re-recording modified steps or changing parameters directly in the tool.
name: Changing the salesperson code on sales order and updating the dimension values
description: "Test recording for an article on the BC Foxer blog. "
start:
profile: BUSINESS MANAGER
steps:
- type: navigate
target:
- page: User Setup
description: Navigate to User Setup
- type: page-shown
source:
page: User Setup
modal: false
runtimeId: b8b
description: Page <caption>User Setup</caption> was shown.
- type: filter
target:
- page: User Setup
runtimeRef: b8b
operation: add
column:
field: User ID
scope: filter
description: Add filter for <caption>User ID</caption> on <caption>User Setup</caption>
- type: input
target:
- page: User Setup
runtimeRef: b8b
- scope: filter
field: User ID
value: =Session.'User ID'
description: Input <value>Session.'User ID'</value> into <caption>User ID</caption>
- type: copy-value
source:
- page: User Setup
runtimeRef: b8b
- repeater: Control1
- field: Salespers./Purch. Code
name: User Setup - Salespers./Purch. Code
valueType: string
description: Copy value from <caption>Salespers./Purch. Code</caption>
- type: close-page
target:
- page: User Setup
runtimeRef: b8b
description: Close page <caption>User Setup</caption>
- type: page-closed
source:
page: User Setup
runtimeId: b8b
description: Page <caption>User Setup</caption> was closed.
- type: navigate
target:
- page: Business Manager Role Center
- action: Sales Orders
description: Navigate to <caption>Sales Orders</caption>
- type: page-shown
source:
page: Sales Order List
modal: false
runtimeId: bd4
description: Page <caption>Sales Orders</caption> was shown.
- type: invoke
target:
- page: Sales Order List
runtimeRef: bd4
- action: Control_New
invokeType: New
description: Invoke New on <caption>New</caption>
- type: page-shown
source:
page: Sales Order
modal: false
runtimeId: bml
description: Page <caption>New - Sales Order</caption> was shown.
- type: focus
target:
- page: Sales Order
runtimeRef: bml
- field: Sell-to Customer No.
description: Focus <caption>Customer No.</caption>
- type: invoke
target:
- page: Sales Order
runtimeRef: bml
- field: Sell-to Customer No.
invokeType: Lookup
description: Invoke Lookup on <caption>Customer No.</caption>
- type: page-shown
source:
page: lookup:Sell-to Customer No.
modal: false
runtimeId: b185
description: Page <caption>Select</caption> was shown.
- type: invoke
target:
- page: lookup:Sell-to Customer No.
runtimeRef: b185
- repeater: repeater
description: Invoke row on <caption>Customer</caption>
- type: page-closed
source:
page: lookup:Sell-to Customer No.
runtimeId: b185
description: Page <caption>Select</caption> was closed.
- type: input
target:
- page: Sales Order
runtimeRef: bml
- field: Salesperson Code
value: =Clipboard.'User Setup - Salespers./Purch. Code'
description: Input <value>Clipboard.'User Setup - Salespers./Purch.
Code'</value> into <caption>Salesperson Code</caption>
- type: focus
target:
- page: Sales Order
runtimeRef: bml
- field: Salesperson Code
description: Focus <caption>Salesperson Code</caption>
- type: page-shown
source:
page: null
automationId: 8da61efd-0002-0003-0507-0b0d1113171d
caption: Confirm
modal: true
runtimeId: b19b
description: Page <caption>Confirm</caption> was shown.
- type: invoke
target:
- page: null
automationId: 8da61efd-0002-0003-0507-0b0d1113171d
caption: Confirm
runtimeRef: b19b
invokeType: Yes
description: Invoke Yes on <caption>Confirm</caption>
- type: page-closed
source:
page: null
runtimeId: b19b
description: Page <caption>Confirm</caption> was closed.
- type: validate
target:
- page: Sales Order
runtimeRef: bml
- field: Salesperson Code
operation: =
value: =Clipboard.'User Setup - Salespers./Purch. Code'
description: Validate <caption>Salesperson Code</caption>
<operation>is</operation> <value>Clipboard.'User Setup - Salespers./Purch.
Code'</value>
Script saved to YAML file — YAML script for the example from the previous screenshot.
Send scenarios to client
We send the prepared scripts in YAML files containing interactive test scenarios to the client. The client can replay them (also using the tool) and use them to test the ordered changes/extensions in the test environment. The client can run each of the scripts in full (automatically going through all the steps and immediately displaying the results of each step and the entire script) or follow each action individually by running the script step-by-step.
When a traditional test scenario is needed
If the client requires test scenarios to be delivered in a traditional format, to provide them as a document (printout) for users to manually go through each step of the process, we can still use YAML files to create them. Chats and AI assistants (such as Microsoft Copilot or OpenAI ChatGPT) based on the increasingly popular GPT-4o model, allows us to use file attachments in the conversation context. Simply upload the YAML file to the AI chat along with a brief description of the attachment and basic context, and it will generate an excellent written test scenario for you.
Which AI is better for test scenarios?
I keep testing which AI handles attaching a YAML file as an information source for the created test scenario better. Both ChatGPT with the GPT-4o model and Microsoft Copilot yield very good results, although they differ. However, I don’t rule out that these differences might be random. In both tools, retrying the response generation can result in better or worse answers, making it challenging to compare results 1:1.
Subjectively, I can say that ChatGPT more often provided responses that clung too rigidly and in detail to the contents of our script file, resulting in the generated test scenario content containing information about the type of scenario step and other technical metadata of the script itself. Conversely, Copilot produced responses that were more natural and adhered to what should be included in a real test scenario.
Additionally, the tool from OpenAI tends to inform us, upon attaching the script file, that the attached YAML file cannot be handled by its standard parser, so it will treat it as a text file. However, this doesn’t affect the outcome too much. Just an interesting tidbit.
Of course, it might happen that some adjustments need to be made to the scenario created by AI based on the script. Still, we’ve got most of the work done. The most important thing is that the GPT model didn’t act blindly; it was based on well-described steps of the automated test scenario contained in the YAML script, so there’s no fear that the AI approached the topic too creatively or loosely.
Let AI do even more for you
GPT-4o created a traditional form of a test script for us, but you still need to copy the query result into your text editor (e.g., MS Word), after pasting the formatting gets messed up, so you have to clean it up, then you have to save it as a PDF, attach it to the task in the ticketing system, whether it’s Asana, Jira or DevOps, etc. There’s still a lot of work left for us! But come on… we’re living in the era of automation and AI ;)
Modify the AI prompt to request simultaneous formatting of the result to the MarkDown syntax ↗ and saving it to file. Download the .md file and place it in the change repository (e.g., in a separate folder for test scenarios). Adjust the steps in your deployment pipeline so that the files from the test case folder are converted to PDF format and attached to the client’s submission as attachments — this is, of course, just an example.
Depending on the software you use for hosting projects, repositories, and exchanging task with your clients, this type of CI/CD pipelines customization can be more or less challenging, but it’s definitely worth the effort.
Check how Microsoft Copilot managed to convert and save the manual test scenario it created into a file that comply with Markdown syntax. Below is the generated file before any edits from my side:
Creating extension documentation
Once we have practiced test scenarios (especially the traditional ones, using the AI model and conversion – see ¶ Creating test scenarios – When a traditional test scenario is needed), creating other types of documentation for any functionality should not be an issue.
Every solution in the form of an ISV extension must have documentation in order to be published on Microsoft AppSource. However, even without this requirement, creating documentation for our solutions should be something obvious, even if we don’t intend to publish our solution on AppSource or if we’re talking about PTE extensions. Unfortunately, this is not always obvious… why? The answer to this question is definitely material for a separate article. Today, I just want to draw your attention to the fact that creating documentation no longer has to be a burdensome task.
Create documentation pages one by one
Using the page scripting tool, we sequentially record the flow through each function and process of our solution. We upload the scripts to our favorite AI chat, requesting the creation of a documentation page for function X using the attached test scenario. The result should be formatted according to MarkDown syntax and saved to a .md file. After any necessary corrections or additions to the content generated by the AI, we can place it directly on our documentation portal. How?
Documentation hosting software, such as docfx ↗ (which is btw. used by Microsoft for Microsoft Learn portal), accepts Markdown files. Simply create new articles on your docfx-based portal using your Markdown files, and you’re all set.
Creating user manuals
If a client asks us to prepare instructions for a specific function in the Business Central standard or within the functionalities of the extensions, we can also use what we learned above. We can record a script from navigating through the given function and ask AI to create a user manual from the attached script containing the test scenario, which we can then correct and supplement with some descriptions, just like in ¶ Creating test scenarios – When a traditional test scenario is needed. Additionally, consider automating the conversion of .md files to PDF with a use of company stationery, and we’re all set.
Or maybe automated manuals?
However, keep in mind that since the page scripting tool is also available to clients, we can approach creating manuals a bit differently. Properly preparing users (training them to use the tool for running scripts and walking through them step-by-step) will allow us to create simple manual instructions in the form of an interactive, automated script. Unfortunately, without additional commentary, but still usable in some cases as a step-by-step hand-holding guide.
By the way, in my opinion what is missing in the page scripting tool is the ability to add a text comment at the step level.
Tutorials in response to “how-to”
And now, imagine a fairly everyday situation in the life of a consultant, when they receive an e-mail (or a ticket in the ticketing system) from a client with a “how-to” question, such as: how to enforce users to select a Variant Code for items that have variants?
In response to such a question, we could simply reply by indicating which page the user should go to in order to set the system’s default behavior for all items, and which page to go to in order to control the system behavior for a specific item record. Simple. You can also use screenshots. The problem is that the user might use our instructions now, but lose our e-mail/ticket in a few weeks and forget where and what they set. They might also not share our response with their colleagues (and we would like him to do so). Therefore, instead of replying in the e-mail or ticket, try recording the…
User tutorial
Using the page scripting tool, we record the path to the Inventory Setup page and focus on the Variant Mandatory if Exists field (without changing its value – let the user do it themselves). We save the script under the name Where to set default Variant Mandatory for all Items.
Next, we record the path to the Item Card and focus on the Variant Mandatory if Exists field for a sample record to show the user that they can override the default setting for selected records. We save the script under the name Where to override default Variant Mandatory setting for selected Item.
We place both scripts in the project document repository, a shared resource on SharePoint, in the team on MS Teams, or another convenient location where the scripts will be accessible not only to the submitter but to all client users. We place both in a folder titled How to enforce Variant Code for items with variants, optionally adding the request/ticket number. We reply to the e-mail or request by providing links to the scripts. This way, we help the client build their own knowledge base while also providing an interactive and automated solution guide.
Automation of repetitive tasks
In a situation where we want to create an automation for a repetitive task (as part of our work in BC), and the built-in workflows or Power Automate templates turn out to be insufficient, unsuitable or overpowered, before we start looking towards extensions, we can seek help in the page scripting tool.
For some repetitive tasks, we can record these actions as a script once and then replay it at any time we need and as many times as we need. Why only for some?
Page scripting limitations
The limitations are imposed by the capabilities of the tool itself. For example, we are unable to record a script that performs the same action on a dynamic set of records. Of course, we can record the action of filtering a list of records based on certain criteria (also dynamic, such as relative date ranges or values retrieved from other areas of the system), but setting up a loop that performs certain operations on all records matching the filter is not possible. However, if you know a way to do this, please leave a comment ↓. I would be pleased if someone could correct me on this.
Recording steps to reproduce the error
If, as a user, you encounter a system error and wish to report it to the Partner, record a script with the steps needed to reproduce the error and include it in your ticket! This will be very helpful in identifying the error and significantly speeding up the entire process.
Recording a script with steps to reproduce the error also guarantees that the issue is indeed repeatable. If, during the attempt to record a script leading to the error, the error does not occur, it might mean that the error was caused by a specific set of conditions affecting the application only at the time of the original issue. In such a case, the user should first conduct additional attempts or tests to ensure that the error no longer appears or to establish under what conditions it occurs. This way, we can avoid submitting an issue that might be met with the response: It works on my machine.
Script conditioning
When we want to record a script for reproducing an error that occurs, for instance, only in a specific document (like specific order or invoice), we need to ensure that during the recording, the document list view is appropriately filtered. The goal is to achieve a list view with only a single record on which the error occurs (preferably filtered by, for example, the document number or in general – by all key table fields). This will guarantee that the script, when run by the service consultant, will select and open the same document from the list, not random.
Conclusion
Here are 6 of my personal examples of using the page scripting tool. I hope I’ve inspired you to try out this functionality in a real-world scenario. Personally, whenever I have to create a test scenario for a client working on the current system version (24+), the day immediately feels a bit nicer 🌞. I’m also keeping my fingers crossed for more of that kind of tools to be added to the system, tools that I can honestly say I don’t know how I managed to live without ;).
I’m curious if you have any other real-world examples of how to utilize the page scripting tool. If so, please share your experience in the comments section ↓
Happy script recordings! ▶️⏯️⏺️
