I read an article where the central message was automation. It was written by @laszloballa here on the Community, and the title is: We Automated the Most Boring Part of Backlog Creation (And You Can Too). I highly recommend reading it! The solution is as simple as it is great. The implementation is a Python-based app, which is able to read a document and parse it using an AI (operating on OpenAI API). The outputs are Stories ordered into Epics. Finally, these elements are stored in ServiceNow's Stories (rm_story) and Epics (rm_epic) tables.
The article was highly inspiring for me, and two thoughts immediately came to mind:
- This solution can be ported into ServiceNow.
- If I build this, I can learn a lot of new things that I haven't had the chance to focus on before, creating real value for my future projects.
So, I jumped into it.
I plan to write a two-part series on this topic. The first post will introduce the application from a functional point of view, then the second will dive into the details of the technical solution.
So first, let's take a look at the application itself, its features, and the journey I went through during the project.
Preparation
Even if it is just a "hobby project", the planning is important. Here are the main steps of my preparation:
- First, I carefully reviewed Laszlo's solution, analyzed the Python code, and understood how it works.
- I checked which features are not available out-of-the-box in ServiceNow, or at least that I'm not aware of. The most significant challenge was extracting text from different file types, like PDF or Word documents. I couldn't find a "native" solution for this in ServiceNow.
- I tried to map the possible pitfalls (although my experience shows that you can never be fully prepared for the unexpected 🙂 ).
- After the analysis, I began designing the solution. I gathered the following key requirements and features:
- AI Integration: Using REST (OpenAI API), with the outbound communication, which is handled by a Flow Action (REST Step).
- Authentication: I relied on ServiceNow’s built-in capabilities, using Token-based authentication via Credentials and Connection Aliases.
- Front-end: I decided to use the UI Builder-based workspace approach.
- Document Processing: To read and parse different file types, I decided to build a custom Next Experience UI Framework component. This allowed me to leverage 3rd party JavaScript libraries directly within ServiceNow to handle PDF and Word files.
- User Experience: A user-friendly design was a priority. The AI-generated content needs to be easily visualized and edited on the front-end before being persisted into ServiceNow's database (rm_epic, rm_story).
Implementation phases
In general, the solution consists of two distinct technical projects:
- Custom Component: A CLI and VS Code-based application leveraging the Next Experience UI Framework. (UX Framework)
- Scoped Application: The core ServiceNow configuration, including UI Builder (UIB), Scripted REST APIs, and Flows.
Phase 1: Custom Component for Document Ingestion
The original Python-based solution reads a text file, generates the prompt, and then executes it using an LLM. I wanted to expand on this feature, so I extended the capability to support PDF and Word documents. This posed a slight challenge, as I needed to find a 3rd party JS library compatible with ServiceNow.
From a UI point of view, this custom component is a simple file-upload HTML element. Once the user clicks on it and selects a document, the component parses the file type, extracts the text, and passes the plain text content back to the UIB Page.
Phase 2: Creating the prompt
At this stage, I essentially adapted Laszlo's solution. His Python code uses a Markdown file (which contains the rules) to generate the prompt. On the ServiceNow side, I converted this into a simple JSON structure, keeping the exact same logic and content.
Phase 3: Executing the prompt
The ultimate goal was to design and realise a generic solution capable of sending the prompt to any LLM. Finally, I decided to handle the entire prompt generation and OpenAI API management on the back-end. For this, I created a Scripted REST API, which can be easily triggered from UIB using a REST-type Data Resource.
This API is responsible for executing the Flow Action. I considered running the Flow asynchronously, but after a second thought decided against it. Since the REST API call from UI Builder is already handled asynchronously, adding another layer of async execution wasn't necessary and wouldn't provide any added value for the end-user.
Phase 4: Processing the response of AI
Processing the response was straightforward since the OpenAI API is highly standardized, and the prompt explicitly defines how the output structure should look. As a result, the generated stories and epics arrive in a well-structured format.
Compared to the original solution, I introduced a major UI enrichment: a front-end interface where the generated Epics and Stories can be easily reviewed and edited. This part was quite challenging because:
- I am not a UX designer. 🙂
- UI Builder does not natively support two-way data binding.
I could manage to solve both issues. The result is solid, at least for a first version! 🙂
Phase 5: Persisting data into ServiceNow's database
Once the user validates the AI-generated content, the data can be persisted into the database with a single button click. Due to the complexity of the data structure, I used a Scripted REST API here as well, managing the execution via a REST-type Data Resource in UI Builder. The script handles the database insertion, and once the operation is complete, the user is provided with a direct way to navigate to and view the newly created Scrum records.
Other UI/UX considerations
Since the back-end processes take some time to complete, it was essential to inform the user that something is happening in the background. To handle this, I utilized modal panels and loading animations.
Additionally, I planned to use a collapsible UI Builder component to allow users to expand and collapse individual Epics, keeping the view clean. However, I discovered that this component lacked a built-in button to trigger the open/close state out-of-the-box. To overcome this limitation, I had to manually implement this toggle feature.
Error handling
When dealing with integrations, errors and system issues are bound to happen eventually. These issues must be visualized to the user in a way that is highly informative without being too technical.
To achieve this, I did comprehensive error handling into all back-end scripts. If an error occurs during an API call or background process, it is gracefully captured and displayed to the user directly on the UI layout.
Summary
I really enjoy working on these types of hobby projects, because they provide a really great learning opportunities. The most crucial part is finding the right motivation to push through and finish them, which isn't always easy! 🙂
During this project, I gained valuable experience in the following areas:
- Reading and parsing PDF or Word documents using 3rd party JS libraries within a custom component.
- Configuring Flow Actions and setting up secure REST API authentication.
- Configuring and utilizing REST-type Data Resources in UI Builder.
- Displaying and making complex data structures editable within UIB.
And now, I'll take a breath. I will dive deep into the technical implementation in my next article!
If you'd like to see how the solution works, check out the video below.
Note: The entire solution and article are my own work. I only used AI to improve grammar and clarity of the post.
#servicenow #developmment #uibuilder #customcomponen
