Linx Software
Sage Intacct is one of the largest cloud-based accounting systems, offering a web service to facilitate integrations. This post covers how you can consume the Sage Intacct web services with Linx, a low-code backend platform.
Further reading: Why APIs and low-code are the perfect match
TLDR: Download the Sage integration template to fast-track your development.
Working with the Sage Intacct web service
This post covers a solution that retrieves a list of customers on sage using the Query and List Customers method.
Sage has good documentation on their web services and how to use them. As of the time of writing, the web service operates similarly to a REST service where you send XML requests.
The web service also has a token-like authentication method. You will need to obtain an access token before you can use any of the other methods. Thus before you make any calls, you need to call the getAPISession endpoint and provide your credentials. This will return a temporary session ID to be used with all other calls. This session ID is only valid for a limited time (specified in the sessiontimeout property in the response). We recommend that a session ID is retrieved in a separate function that you can reuse in all other integration functions on Linx.
Once you have a session ID, you can start to call other functions of the web service to do things such as retrieve customer lists, access accounting data and many other features offered by Sage.
XML vs JSON
The Sage web service expects XML requests. Users should note that when using the CallRESTEndpoint function, you should pay attention to format the XML precisely to match what Sage Intacct expects.
You can receive a response in XML or JSON based on your chosen version and configuration.
Calling Sage Intact Web Services with Linx
To start, we will call the web service with the CallRESTEndpoint function. The only trick is to format the request body correctly, as the web service expects an XML body. To do this, we will create a complex type, i.e. a structure that resembles the XML object. Once the structure is created, it is a simple matter of populating the values and then parsing them to XML with the XMLWriter function.
In our example, we will retrieve a list of customers using the Query and List Customers method. To do this, two things need to happen;
- first, a session ID needs to be retrieved, and
- the XML body needs to be constructed.
Authentication
Retrieving the session ID can be done by calling the getAPISession method. Creating a function specifically for retrieving the session ID will allow you to reuse that function whenever you need it.
In the example, the function created to get the Session ID is called generateAPISession. This function will receive the company credentials as input parameters (company ID, password and user ID). We created the type for this request using the Import functionality for types by importing the XML of the request body. After making a few adjustments (adding nodes that could not be imported), we assigned values to the type, mapping the credentials and required information. The function we also specified as . We also had to set the controlid property in the functions object. This can be done using a SetValue function after the type has been parsed to XML.
The request can be sent using a REST function, and you can import the response as a type to make things more manageable. This will allow easy access to the session ID that can be returned as the result of this function. Since the access function is reusable, it can be placed in the getCustomers function or any other function when you need to call the web service.
Get Customer List
Next, you can create the function to call the specific method you need. As per the example, we focused on getting a list of customers. This function is more complex than the generateAPISession function as data will be returned, and you might need to page through data (the maximum is 2000 records per call as of the time of writing).
To do this, we used a loop that will call the endpoint continuously until no more records are left. This was done by declaring the page size and offset. The maximum number of records are stored, and if the offset is less than the maximum number of records (the max page size), then it is assumed that there are no more records and the service does not have to be called again. The offset is also passed in the body of the call; this allows Sage to know from what record to return results.
The call is made with the response body set as JSON. When the response is received, use a JSONReader to map the fields to those declared in a custom type (this can also be imported). You need to add the received values to a list as part of the loop. This will ensure that values are not lost when the next iteration of the loop starts.
Note: There are several ways to do this. We chose this approach in the example.
Finally, once the list is complete and the data has been received, you can return the result or do what you need with the data. The beauty of reusable functions is that you can rely on that functionality later. Making your functions as small as possible allows for easier debugging and enhancement.
Use settings for fast-paced development
You may need to reuse a specific value across various functions during your development. In such a case, creating a setting will be helpful. These settings can be reused in many places. We made settings for all the authentication credentials, with some of them (specifically the password) being a secret, meaning the value will not be visible. What makes settings especially useful is that you can set them in the Linx Server to match a specific value for a particular environment. If you have a test server, you can use a different test version of your Sage credentials for that environment.
Now that you have a function to call the API and retrieve the required data, you can continue with your integration development. Storing the data in a database, making it available via a quick access REST API, formulating it for reporting or even integrating it into another application, the sky is the limit.
Final thoughts
Integrations come with unique challenges, depending on what system you need to integrate with, what you need to do with the data and what business rules you need to apply.
Working with the Sage Intacct API can be simplified by choosing a solution that allows you to streamline the web service call and manipulate the data. You can use the Sage Intacct web service with Linx to get the job done efficiently, and after you have the data, you can do what you need with it.
Get the templated sample solution in the Linx Github repo.
