I am to add comprehensive textual error description for every DMCC service request.
I perform these steps to unsure as better description as possible:
1. On error from AES recover the exact service, that was requested, by invokeId.
2. For the given service I switch CSTAErrorCode value to map the description string, which I got from the DMCC documentation.
3. If that gave nothing, I try to map CSTAErrorCode with TSAPI errors and get the description from there.
4. If that fails too, I take the description from CSTA.

The problem is, that both TSAPI and DMCC error codes so poorly descripted by themselves. Furthermore, sometimes DMCC mapping of TSAPI erros is is not evident. Here is a list of problems:
1. Some DMCC services documentation miss any error code description (for example MonitoStart, DirectedPickupCall, SelectiveListeningHold and so on).
2. Some services of both DMCC and TSAPI emit error codes which are not present in corresponding documentation. And the mapping is also very incomplete and inconsistent (OperationErrors::parameterTypeNotSupported is not there for AlternateCall DMCC request, but it presents as MISTYPED_ARGUMENT_REJECTION in TSAPI, and this mapping is made for ConferenceCall, HoldCall and many others. On the contrary for SingleStepTransfer there is no MISTYPED_ARGUMENT_REJECTION in TSAPI docs, but OperationErrors::parameterTypeNotSupported is there in DMCC docs. The list of such flaws is very long.).
3. Documentation contains grammatical and factual errors. Wordings of the same description varies from service to service for no reason (SingleStepTransferCall service error description was simply copy pasted from TransferCall and contains reference to heldCall parameter, which has nothing to do with SingleStepTransferCall).

All in all, from error handling perspective this doesn't look like enterprise grade piece of software. Currently I think about reversing DMCC binaries form AES to gather any concrete information about mapping from TSAPI. Even though TSAPI error mapping to CSTA is not ideal (if you got INVALID_CSTA_DEVICE_IDENTIFIER for cstaSetAgentState, you can't tell what is invalid: phone extension or agent login/password), it still contains way better descriptions then DMCC. Why would they even prepend 'Sent if ' to every description?

Has anyone stumbled into this? Is there any simpler way?

You can submit any errors you see in the documentation to document@avaya.com - I find it best to provide a URL to the document its document ID (usually in the bottom right of the first page of the document), and then a description of the error, and if possible what the corrected text would be.

It is a strange request you have been asked to create a solution for. I presume from someone who hasn't worked closely with DMCC, nor perhaps with telecommunication systems with a long legacy.

Has anyone stumbled into this? yes
Is there any simpler way? not that I have ever found.

In the beginning, there was ASAI (Q9.31 based call control). This is also known as DLG.
that beget CVLAN
then there was CSTA (yep the international standard came after Avaya's - well then AT&T's - CTI solution had existed for years)
then there was TSAPI - Lucent's implementation of CSTA-3
more recently there was DMCC - Avaya's implementation of CSTA-1

Later DMCC incorporated a lot of what was in TSAPI as the call control service, but leveraged the documentation. This work was largly done by a single developer who felt a single unified API was the 'right' thing to do.

Thus there are 20 years of Avaya documents covering what amounts to at least 3 layers of software with contributions made by 100's of people at various times. Literally 1000's of applications have been created against this set of CTI services.

As someone that has worked in this domain for a decade, I first look at DMCC documentation, if it isn't answering my question I look at the TSAPI documentation, if that isn't helping I look at the ASAI document and even then I find my self reviewing the source code and trying to resolve conflicting statements. I see the same mistakes you do, and create JIRAs documenting them. Then, I must wait for someone to prioritize the JIRAS and take the time to correct them. Some documents are not being updated anymore (ASAI) because Avaya has stopped publicly updating the protocol and thus those mistakes will exist indefinitely.

JohnBiggs wrote:
It is a strange request you have been asked to create a solution for. I presume from someone who hasn't worked closely with DMCC, nor perhaps with telecommunication systems with a long legacy.

As someone that has worked in this domain for a decade, I first look at DMCC documentation, if it isn't answering my question I look at the TSAPI documentation, if that isn't helping I look at the ASAI document and even then I find my self reviewing the source code and trying to resolve conflicting statements. I see the same mistakes you do, and create JIRAs documenting them. Then, I must wait for someone to prioritize the JIRAS and take the time to correct them. Some documents are not being updated anymore (ASAI) because Avaya has stopped publicly updating the protocol and thus those mistakes will exist indefinitely.

What JIRA do you mention? Is it location provided in a reply from document@avaya.com? If it is AVAYA support, I dont have an account.

This is not about mistakes on implementation step of development.
I have to move these descriptions into the source code to enable system administrators to solve problems like wrong agent login or license shortage. An ordinary user wants to see a comprehensive text message instead of RESOURCE_BUSY, if he tries to make a third call on a 2-line phone. These descriptions are the last resort, in case the application doesn't need to handle the exact situation, so it includes them as a part of a text message.

JIRA is the repository Avaya uses internally to track defects. There is not a mechanism for outside parties to directly access Avaya's JIRA system. Your pathway is to email to document@avaya.com, they in turn will probably open a JIRA on your behalf.