Introduction
A customer needed to retrieve captions from Sage CRM using the SOAP web services.
Sage CRM is a system that controls its user interface using settings contained in the database. The database doesn't just hold the information about the contacts, companies, tasks and opportunities that are vital to the business, it also holds data that describes the lists and screens that the user sees.
Sage CRM has separated the code that knows how to draw a button, or a field, or a screen from the properties that define the name of the button, the data the field should display, the field that the screen should contain.
The data that describes Sage CRM's interface, workflow and business rules is called metadata.
About SOAP
Sage CRM's web service API (application programming interface) enables developers to manipulate CRM records remotely with SOAP (Simple Object Access Protocol) over HTTP using XML (Extensible Markup Language). It is possible to access a CRM server or a hosted system from a specified client machine (typically another server) to read, create, update, or delete records for each exposed entity, for example, Companies, People, Opportunities, Cases, Quotes and Orders.
The limitation of the SOAP web services
Sage CRM's SOAP web services do not provide users with a (Graphical User Interface) GUI, which is the case with the .NET and COM APIs. Instead, web services share business logic, data, and some processes through a programmatic interface across a network.
But I need to access the metadata that controls the translations.
Sage CRM's SOAP web services are documented within the developer guide for each version of Sage CRM: https://help.sagecrm.com/
The SOAP interface does not have a method to retrieve translations from the "captions table" in metadata. (custom_captions)
There is some default behaviour involving translations using the getdropdownvalues() method.
See: Selection Lists in Web Services
https://www.sagecity.com/sage-global-solutions/sage-crm/b/sage-crm-hints-tips-and-tricks/posts/selection-lists-in-web-services
The caption code for an item in a selection list is the data that is stored as the value of a field that is a selection list. The getdropdownvalues() returns the translation for the caption code, BUT this is always the translation for the default application language and not the user's language.
So how can we get the translations that we need?
Mixing SOAP with REST
When accessing Sage CRM via the SOAP Web Services API a user session needs to be created.
private WebService WS=new WebService();
private logonresult SID;
SID=WS.logon("wsuser","x3%b0H2");
WS.SessionHeaderValue = new SessionHeader();
WS.SessionHeaderValue.sessionId = SID.sessionid;
//
//do work here
//
WS.logoff(SID.sessionid);
That Session ID (SID) can be used for certain REST calls.
Sage CRM 2021 R1 saw a major expansion of the RESTful API that included Metadata discovery.
See:
The Sage CRM 2021 R1 release has added translation to the RESTful API.
A developer can post a set of caption family data to an endpoint and then have the translations returned.
http://{{server}}/sdata/{{install}}j/metadata/-/$service/getTrans?SID={{sid}}
The metadata discovery method getTrans will help developers who are creating new extensions and integrations with Sage CRM.