FAQs

What is a folder in X3?

A folder is a structure that stores data related to a set of companies willing to share the same common tables (business partners, products) and to have the ability to create reports aggregating the data on groups of companies with database queries on a single schema. It is implemented as a unique database user with a set of tables storing parameters and user data.

What is a scope in X3 API?

As a developer, when you create a pairing request you need to pass a Scope. Scope represents the authorization that will be associated with your access tokens. It must include the list of APIs you want to consume. For graphQL API, we use:

• api.graphQL

Note : API related to token management, folder listing are not part of the scope since it’s a requirement for developer to have access to it.

Specificity of the graphQL API

If you include the graphQL API in the scope, you also need to pass a parameter related to the kind of data you can read and write. You have 2 kind of data access, by named user, or by businessDomain :

• If you prefer the user access method, then simply add “user.?” in the scope. The question mark will be replaced by the login of the user that accept the pairing request. Future call on the graphQL API related to the access token will be done through this user. You inherit its access rights and every record created or edited will be associated to this user in the audit.

• The other right management method is the business domain. You need to pass a list of s in the scope, at least one. For now there is only one domain that represents all the data available through gridFS API : businessDomain.ALL. The list of valid domains is accessible on the Root API. In the future we will introduce more precise domains like “SALES” or “ACCOUNTING”.

Note : If you specify nothing along with graphQL API we will automatically include businessDomain.ALL in the requested scope.

When to pick user.? And when to use businessDomain?

First, let’s remind that this elements only applies to the graphQL API. If you are using another API you don’t need to include these elements to the scope. If you are developing a cloud to cloud application for batch synchronization that would require a single access token across all user, then using a businessDomain is a good option. If you need to read / write elements associated to a specific user, as for instance developing a mobile app for a salesperson to create quotes, then it’s probably a better option to use user.?.

What about folders?

Folder will be added to the scope by the end-user in X3. When he reviews your pairing request, he selects the X3 folders he want to associated your access token with. There are 2 ways for you to know the folder you can access to once you have your tokens. First way is to review the scope returned by token API, second way is to call the folder API since only the authorized folders will be part of the response.

Example of valid scopes

• “api.graphQL user.?”
• “api.graphQL businessDomain.ALL”

What is a regional API endpoint in X3?

At the end of pairing process, if the regional API endpoint you are using is not associated to the customer configuration, a parameter called endpoint will be present in the callback that gives you the access code to convert into tokens. The 3rd party application has to use this endpoint for further calls instead of its known regional root API endpoint.

Maximum payload limit for GraphQL API

The GraphQL API has limit on the payloads size (request & response): their size cannot exceed 6MB.