As you may already know, starting Sage X3 2021 R2 (V12), a new integration pathway has been introduced; the mighty GraphQL. Invented by Facebook to used internally back in 2012, GraphQL has gained massive popularity for its lightweight query and response profiles and the good news is Sage X3 has been embracing this new technology for integration with third-party applications since mid-2021. In fact, X3's new ADC (Automated Data Collection) module uses GraphQL to integrate transactions and query data from X3.
In this discussion, I am going to show you how you can start using X3's GraphQL interface and take it for a spin using both X3's internal GraphQL IDE, called GraphiQL and Postman, so let's dig in:
First of all, you need to make sure you are on at least 2021R2. In this tutorial I am using the latest version of X3, i.e. 2022 R1. Sage is adding new queries and integrations (also called mutations in GraphQL lingo) with every release, so it is worth being on the latest version. To see the latest additions to the GraphQL interface with every release, please refer to the Release Notes on public help centre.
Now, it's time to connect to Sage X3's GraphiQL tool to run a basic query.
- Connect to Syracuse and log in as usual using your admin credentials
- open a new tab and navgate to: http://[YourSyracuseServer:Port]/xtrem/explorer/
- for instance, http://x3erpv12sqlvm:8124/xtrem/explorer/
- Now you should see GraphiQL's interface which looks like this:
- If you can see this interface, you can now test drive GraphQL to query data from X3 and write (integrate) transactions to it. As I said earlier, with every new release, there comes new query types and supported objects.
- We’ll start with a simple query, and get a list of products with their ID, Description 1 and whether they are of Received type. You will notice that GraphiQL will assist you in wrting code as you type, making it a very simple tool to learn.
- Now click the "Run" button on the top right to execute the command. You will receive a JSON response.
- Great right? I know. You can also use Postman to connect to the system and test the queries there, but Postman won't help you with auto-completion of code, so it is better to use both tools to achieve better results. e.g. GraphiQL to write and test the code and Postman to save and share it with others
Let's now go to Postman and run the same query, shall we?
- Open Postman and create a new Workspace. Let's call it "Sage X3 GraphQL" this time.
- Click on Create Collection button and call it GraphQL X3
- In the Authorization tab, choose Basic Authentication and enter your Syracuse admin credentials. You can also use other authentication methods for better security but this time we are going to use Basic Authentication
- Now, add a Request to your Collection by Right Clicking on it and change its type to POST. Remember, it GraphQL, regardless of whether you are querying or integrating data, you must always use POST. Enter the following URL in the Request URL Section: http://[YourSyracuseServer:Port]/xtrem/api
- We will also rename this new request to "Product Query"
- Now make sure the Authorization tab says "Inherit from Parent" so this query uses the same authentication details of its parent, i.e. the Workspace
- Now go the Body of the Request and Choose GraphQL as your language of choice.
- This will open two columns, one for the query and one for the Variables. Noticed the similarity between this environment and X3's internal GraphiQL?
- You will learn more about using Variables in your Queries later by referring to the Sage Developer Portal linked below.
- Now Let's insert the same query into postman and run the request:
- We will receive the response in JSON format
To learn more about the API reference library and more examples, please go to Sage Developer portal, GraphQL section.Fast track to GraphQL | Sage Developer
I hope you enjoyed this article as much as I did writing it.
Please don't hesitate to comment your thoughts and queries below and I will do my best to respond promptly.
