Introduction
The aim of this document is to confirm that you can connect to Xledger via our GraphQL API, as this is the first step in developing your integration. For testing purposes, please complete this test in your Xledger Demo environment and whilst in the development stage of building your integration, please also complete this work in your Demo environment.
Regarding your live and demo environments, some key information must be considered. The Xledger live environment copies over to the demo environment every two weeks and always takes place on a Sunday. What this means is that all data in the demo environment will be overwritten once the refresh is completed, this includes your GraphQL API tokens as well. So any test data that is created in the demo environment will be overwritten and any GraphQL tokens generated in the demo environment will also be overwritten or removed.
GraphQL Token
The first step is to generate your Xledger GraphQL API token, which will be used to authenticate your connection. As just mentioned above, when you create your token in the demo environment, this will be removed every two weeks, due to the refresh. This token must be created by a user with the Domain Administrator role.
To get around having to create a token every two weeks, we recommend that you generate the token in the demo environment first, with the relevant access. Then replicate the same steps in your live environment to generate another token. Once the two weeks are up, the demo token you generated will become void and you can then use the live token in both the live and demo environments. All you have to do for this to work is to change the URL to point to either environment. These are the following Xledger GraphQL endpoints:
Live: https://www.xledger.net/graphql
Demo: https://demo.xledger.net/graphql
While completing the connectivity test, you will only be doing this in your demo environment. Please see the below, on how to generate your Xledger token:
- Firstly, please login into your Xledger Demo API token environment, using the URL below
- You should now be logged in and redirected to the following screen:
- Please select “Generate new token”. The following screen will then be returned:
- Give your token a description of “Connectivity test”.
- The next step is to give your token, the access it requires. For our connectivity test, we will be creating a new customer and then querying the customer's table, to find your newly created record. To give your token access to do this, please expand the “Common” scope.
- You will then need to tick both the “Read” and “Write” boxes on the following scopes: Company and customer. (Please note that the reason why you need to select both Company and Customer, is because a customer has to be added to a company.) Like so:
- Once both scopes have been selected, please click on “Generate token” at the bottom of the page. Once you have done this, you will be presented with your token, like so:
- Please store this token, for future use.
Connectivity Test
Now you have generated your GraphQL token, we can start the connectivity test. In this example, I will be using Postman, but please feel free to test with whatever tool you will be using to build your integration.
Please note that at the bottom of this document, is an attachment of a completed Postman collection. This Postman collection contains the GraphQL query and mutations required to complete this connectivity test. All you need to do is follow steps 8 to 12 below, on each request as this authenticates your requests. If you would like to start from the very beginning and build your own Postman collection, please follow the steps below:
- Your first step in Postman will be to create a new HTTP request. To do this please go to your workspace and select “New”.
- The following pop-up will be presented to you:
- Please select "HTTP Request".
- Name this “Add Companies”, followed by saving your request.
- The first setting you need to change is the GET. Please click on the drop-down and select “Post”.
- Next, you will need to enter the Xledger GraphQL URL. Please paste the following URL into the field which says “Enter request URL”: https://demo.xledger.net/graphql
- The next thing to configure is our authorization header, please go to the “Authorization” tab and select “No auth”.
- Followed by then going to the “Headers” tab. Where you should have the following screen:
- You now need to create the Authorization header, please go to the last row on the headers table.
- In the “Key” column, please enter “Authorization”.
- In the value column, please enter “token <then enter your GraphQL token here>”
- Next, we need to add the Add Companies mutation to the body tab.
- Once you are in the body tab, please select the GraphQL option.
- Please paste the following mutation in the Query box, followed by saving your request:
mutation {
addCompanies(inputs: {node: {description: "Connectivity test – <Your company name>"}}) {
edges {
node {
dbId
}
}
}
}
- You can now send the mutation, which will create your Company in Xledger. If your test is successful, the following will be returned, please leave this open as you will need the dbId later.
- The next step is to create our customer record. Please repeat steps 1 to 10 but name this request “Add Customers”.
- Next, you need to add the add Customers mutation to the body tab.
- Once you are in the body tab, please select the GraphQL option.
- Please paste the following mutation in the Query box. You will then need to enter the dbId number returned from the “Add Companies” mutation, which you completed earlier, into the company: dbId field, like so:
mutation{
addCustomers(inputs:{node:{
description: "Connectivity test – <Your company name>"
company: {dbId: 30631187}
}}) {
edges {
node {
dbId
}
}
}
}
- Again, you can now send the mutation, which will create your new customer to your newly created company. If your test is successful, your customer dbId will be returned to you. Please keep this for your next test.
- The final test is to query your newly created customer. This is to ensure that you can successfully retrieve your data. Again, please recreate steps 1 to 10, please name this request “Get Customer”.
- Next, we need to add the Get Customer query to the body tab.
- Once you are in the body tab, please select the GraphQL option.
- Please paste the following query into the Query box, followed by saving your request. You will then need to enter the dbId number returned from the “Add Customers” mutation, which you completed earlier, into the customer: dbId field, like so:
{
customer(dbId: "30632041") {
dbId
description
company {
description
}
}
}
- You can now send the query, and if successful your newly created customer will be returned: