Documented APICriterionRequired
Has public documentation covering purpose, syntax, parameters, return value and usage conditions. It should be the first choice for customizations.
TECHNICAL GOVERNANCEPublished
Using internal Protheus resources: risks and best practices
Documented API → public contract | Internal resource → no compatibility guaranteeGuide decisions about internal Protheus functions, classes and variables without presenting undocumented resources as recommended APIs.
Overview
This page does not recommend using internal resources. Its purpose is to support risk analysis when an identifier appears in legacy code, old examples, third-party sources, include files, standard routines or historical documentation. Not every technically available resource is a public API. TOTVS warns that internal or undocumented functions, classes and variables are outside standard support, may change behavior and may be blocked or discontinued without notice. The safest decision is to prefer documented APIs, record exceptions and review internal dependencies before release upgrades.
Syntax
Documented API → public contract | Internal resource → no compatibility guaranteeParameters
Internal resourceCriterionRequired
Exists for product use, may depend on implicit context and provides no public compatibility contract.
Legacy resourceCriterionOptional
May appear in old sources or materials, but must be confirmed for the current release before reuse.
Controlled exceptionTechnical decisionOptional
Temporary documented use with owner, reason, evaluated alternative, tests, accepted risk and replacement plan.
Return value
The page guides a technical decision: use a documented resource, replace the internal dependency, isolate a temporary exception or submit the requirement through official channels.
Prefer a documented alternative
#Include "TOTVS.ch"
User Function ExTechnicalDecision()
Local cMessage := "Processing completed"
// Prefer public and documented resources.
MsgInfo(cMessage, "Result")
ReturnExpected result
The example uses a documented public function. In a real migration, replace the internal call with an equivalent official API or with your own tested implementation.
Checklist before using an internal resource
// Antes de usar:
// 1. Existe documentação oficial?
// 2. A documentação vale para a release usada?
// 3. Há API pública equivalente?
// 4. A rotina roda em interface, job ou serviço?
// 5. O risco foi registrado?
// 6. Existe teste de regressão?
// 7. Há plano de substituição?Expected result
If the answers are unclear, avoid the use or treat it as a temporary technical exception.
Minimum exception record
Recurso: <identificador>
Motivo: <necessidade atendida>
Alternativa avaliada: <API pública ou implementação própria>
Release testada: <versão>
Responsável: <nome/área>
Evidência: <teste, chamado, homologação>
Revisar em: <data>Expected result
Document the resource, reason, evaluated alternative, expected impact, owner, tested version, validation evidence and review date.
- Search TDN and the TOTVS Support Center before using an identifier.
- Confirm that documentation matches the target release, module and execution context.
- Treat resources found only in source code, third-party examples or historical material as unsupported until official documentation proves otherwise.
- Prefer documented APIs, documented entry points, public Framework classes or your own implementation.
- For existing production dependencies, record location, reason, risk and replacement path.
- Include this check in release reviews, customization audits, incident analysis and technical-debt cleanup.
- An internal resource may work in one release and fail in another without being treated as a public-contract break.
- Standard product code may rely on internal state, execution order, private variables or context unavailable to a customization.
- Jobs, web services, automated routines and user interfaces may react differently to the same internal resource.
- Wrapping an internal call limits spread, but does not make it supported.
- StaticCall() and PTInternal() are examples cited by TOTVS in an internal-property alert, with compilation restrictions as of release 12.1.33.
- Copied lists from old material may become outdated; the official source and supported release remain the validation reference.
Comments
There are no approved comments yet.
Sign in with Google or Microsoft to comment.