Hello Team,
I have created two ODC applications as part of the document review solution:
1. ODC AI Agent
This agent accepts the uploaded document as binary content along with the file name, document label, and file format. It analyzes the document based on the system prompt configured in the agent and returns the review result in the required JSON format.
2. ODC Application – REST API
I have exposed a REST API through this application so that the AI document review functionality can be consumed by external applications, including an OutSystems 11 application.
The current API payload is:
{
"DocumentReviewId": 1,
"FileName": "Sample_Legal_Advice.txt",
"FileContent": "Binary Content",
"DocumentLabel": "Advice",
"FileFormat": "plain/text"
}
The AI Agent analyzes the document based on the configured prompt and generates the response.
Dynamic Review ID
One issue I have noticed is that the generated response contains a static/sequential review ID, for example:
"reviewId": "RV-001"
or
"reviewId": "RV-002"
Instead, I would like the response reviewId to be dynamically generated based on the DocumentReviewId provided in the request.
For example:
- DocumentReviewId = 1 → reviewId = "RV-00001"
- DocumentReviewId = 10 → reviewId = "RV-00010"
- DocumentReviewId = 1000 → reviewId = "RV-01000"
I would like to understand the best way to pass this dynamic value to the AI Agent so that it uses the ID from the request rather than generating its own value.
OutSystems 11 Integration
I would also like guidance on the recommended approach for consuming this API from an OutSystems 11 Integration Service (IS) module, including:
- Proper REST API integration and request/response handling
- Exception handling and meaningful error messages
- Retry mechanism for transient failures
- Circuit breaker pattern, if appropriate
- Handling API timeouts and unavailable services
- Database-based error/exception logging
- Maintaining a clean separation between integration, business logic, and logging
- Best practices for making the solution reliable and maintainable
The main objective is to have a robust AI document review integration where the request ID is correctly reflected in the response and the OutSystems 11 integration handles failures, retries, and logging appropriately.
I would appreciate your recommendations on the best architecture and implementation approach for this solution.
Hi Pradip,First, I am unable to open your OML files in ODC Studio. It is saying that it is written in Service Studio. Therefore, my answer is based on your description.For the Review ID:Don't ask the AI Agent to create the review ID. Create it in your code.AI Models are good at reading and judging a document. They are not good at copying an ID exactly, event if you put it in the prompt. You already have DocumentReviewId in the request, use it instead of relying on the model for this.In the ODC REST API:1. Build the ID in the server action: "RV-" + FormatText(IntegerToText(DocumentReviewId), 5, 5, True, "0"). This gives RV-00001, etc.2. Remove reviewId from the output you ask the agent for. Or keep it, but ignore it.3. After you deserialize the agent's JSON, set the reviewId to your value before the API returns.In short, the agent does the review. Your code owns the IDsFor O11 side, this is how I would build it:* Create an IS module for the consumed REST API. Expose one public server action, for example DocumentReview_Submit. It returns the response plus IsScucess and ErrorMessage. Other modules calls this server action and not the REST Method directly.* Set the timeout on the REST method yourself. AI calls are slow and can take different amount of time, so don't use the default.* Use OnAfterResponse to turn errors into clear user exceptions.* Outsystems does not retry REST calls for you, so you need to add the retry logic: https://www.outsystems.com/forums/discussion/87825/the-timeout-defined-in-the-rest-api/* Keep direct retries to one or two because each retry makes the user wait longer and cost more tokens. For anything more, use a queue pattern in CS module. Save a request record with Status, AttemptCount and NextAttemptOn. Then let a Light BPT process retry it later.* For circuit breaker, you can try this: https://www.outsystems.com/forge/component-documentation/18985/circuit-breaker-service-o1. OutSystems also explains the pattern here: https://www.outsystems.com/blog/posts/o11-odc-circuit-breakers/* For logging, Service Center already logs integration calls. While testing, you can raise the log level on the module to see the full request and response. For database logging, create an IntegrationLog entity in a separate logging module. Store ReviewId, attemtpt number, status code, duration and error. Also send DocumentReviewId as the header, so you can use it as reference for both O11 and ODC.Don't forget Security:Before you go live, add authentication to your exposed REST API. Without it, anyone with the URL can call it and use your AI tokens. In ODC, a common way is to set Authentication to Custom and check an API Key or token in the OnAuthentication action. You can refer to this thread: https://www.outsystems.com/forums/discussion/92103/basic-authorisation-on-exposed-rest-api-for-odc/So, this gives you three layers in O11:* IS module for the API call* a CS for the review process* a logging module for the audit trail.
Hi @Michael de Guzman
Thank you for your valuable feedback.
I have implemented an application that interacts with an API, and I would like to get your feedback on the current implementation.
Could you please review the approach and assess whether it follows industry best practices for an enterprise application? Please highlight any potential issues, security concerns, performance bottlenecks, or scalability limitations, and recommend the most appropriate implementation approach.
Based on your feedback, I will refine the implementation and proceed with the recommended solution.