¶ Entities
Entities in eWastra represent the different data elements used in the platform. Examples are Freight Documents, Contacts, Companies, Products, Users, ...
All entities in eWastra are identified using an internal id which is assigned when an entity is created on the platform. All entities also have an external identifier - "externalId" in the data element - which can provided by the system that integrates with the platform.
¶ Associations
Entities like the transport document can contain associations to other entities. For example the transport document contains a Consignor, Consignee, Pickup place, Delivery place, Goods, ...
When creating or updating a tranport document, these entities can be supplied "inline" or by "reference".
Inline means that all relevant information of an entity is present in the dataset
{
...
"externalId": "{{$guid}}",
"consignor": {
"responsibleContact": {
"emailAddress": "test@acmechemicals.be",
"faxNumber": "1959",
"name": "Bob ",
"telephoneNumber": "+3200000000"
},
"address": {
"additionalLine": "",
"streetAddress": "Baron de Maerelaan 8",
"postalcode": "8380",
"city": "Zeebrugge",
"countryCode": "BE"
},
"externalId": "EXT46464646",
"emailAddress": "stefan.gevaert@pionira.be",
"name": "ACME Chemicals",
"organizationNumber": "BE050568812022"
}
...
}
By reference means that only the "id" or "externalId" is present in the dataset
sidenote : an externalId is a chosen unique reference to an entity
{
...
"consignor": {
"id": 1490107,
or
"externalID": "CUST8501"
}
...
}
Updating entities occurs automatically when using the inline method.
When using the reference method the fields containing the updated information should be passed as well.
An example: Update a contact's (consignor) email adress
{
"consignor": {
"externalId": "CUST8501",
"emailAdress": "simon.depuydt@pionira.be"
}
}
¶ Tree-structured organizations
¶ General concept
Each organization on eWastra can have one or multiple sub organizations. Subsequently, each sub organization can have again one or multiple sub organizations, thus creating a tree-structured setup.
A visualization of such a typical tree is displayed.
Visually displayed by {level ...n}, indicates that there can be unlimited number of levels.
¶ Purpose of a Tree-structured organization structure
The main purpose, is to implement a sort of access control across your organization.
This implies users from higher level organizations having acces to documents of its own organization and linked lower level organizations.
Based on the example above, the following access control is present
-
logged in as a user of Pionira Group
Pionira Group (Level 1) has access to all documents from the entire organization as it is linked to Pionira site 1,2 3. In addition Pionira site 1 is subsequently linked to Pionira site 1 inbound & outbound providing access to all documents. This means a user from Pionira Group can access documents from all 6 organizations on the chart. -
Logged in as a user of Pionira site 1
Pionira site 1 has acces to it's own documents and documents from it's linked lower level organizations, Pionira site 1 inbound & outbound -
Logged in as a user of Pionira site 2 and 3
Pionira site 2 and 3 have the same logic. As they have no linked lower level organizations they only have access to their own documents -
Logged in as a user of Pionira site 1 inbound and outbound
Pionira site 1 inbound and outbound have the same logic. As they have no linked lower level organizations they only have access to their own documents
| Has access to | Pionira Group | Pionira site 1 | Pionira site 2 | Pionira site 3 | Pionira site 1 inbound | Pionira site 1 outbound |
|---|---|---|---|---|---|---|
| Pionira Group | Yes | Yes | Yes | Yes | Yes | Yes |
| Pionira site 1 | No | Yes | No | No | Yes | Yes |
| Pionira site 2 | No | No | Yes | No | No | No |
| Pionira site 3 | No | No | No | Yes | No | No |
| Pionira site 1 Inbound | No | No | No | No | yes | No |
| Pionira site 1 Outbound | No | No | No | No | No | Yes |
¶ Good to know regarding to the Tree-structure
Sub organization are a special type of contacts and show following behaviour:
- Lower level organizations are automatically added as a contact to the direct higher level organizations ( one level up)
- Changing a sub organizations information (such streetadress, emailadress ...) cannot be done through API this must be done in the administration page.
This means referring to the example above that when Pionira Group creates a document stating Pionira site 1 as consignor. All the information of Pionira site 1 will be taken from the settings in the admin page of the sub organization and not from the inforamtion provided in the JSon.
Is a Tree-structured setup something for your organization? Please contact support@pionira.be or your contact person within Pionira to setup the configuration.
¶ Focus: difference in working with suborganisations vs regular contacts
Suborganisations and contacts can both act as different parties on each document ( consignor, consignee, pickup contact, delivery contact, primary carrier, subcarrier, successive carrier, collector, producer and treatment operator).
To register new parties the process depends on wether or not it concers a suborganzation of your existing company.
Case1: The newly to create contact is a suborganization of your existing company
- In this case ask your pionira@support.be or your contact person to configure your suborganization
- The newly created company will automatically be listed as a contact to your existing company
More information regarding a tree structure in general can be found here: https://docs.xynaps.net/en/Integrations/Concepts#tree-structured-organizations
Case2: The newly to create contact is a suborganization of a suborganization to your existing company
- In this case ask your pionira@support.be or your contact person to configure your suborganization
- The newly created suborganization will not be automatically listed as a contact to your eisting organization.
- You will need to create the contact and if desirable link to contact.
More information on how to create and link contacts independently from a transportdocument can be found here:
https://docs.xynaps.net/en/Integrations/APIHowTo#creating-and-inviting-a-contact-using-the-api
You can also declare new contacts when creating a new transportdocument:
https://docs.xynaps.net/en/Integrations/APIHowTo#contacts-general
Case3: The newly to create contact is not a suborganization to your organization
- You will need to create the contact and if desirable link to contact.
More information on how to create and link contacts independently from a transportdocument can be found here:
https://docs.xynaps.net/en/Integrations/APIHowTo#creating-and-inviting-a-contact-using-the-api
You can also declare new contacts when creating a new transportdocument:
https://docs.xynaps.net/en/Integrations/APIHowTo#contacts-general