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. This post covers a solution that retrieves a list of customers on sage using the Query and List Customers method.
TLDR: Download the demo solution to fast-track your development.
Calling Sage Intact Web Services
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 <getAPISession/>. Wealso 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.
Using 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.
Next steps
- Get the Sage Intacct sample solution (Github)
- Further reading: 5 Tips to Overcome System Integration Challenges
- Application Integration Use Case