To help integrators, we have added the embedded entities on the API. It reduces the time needed to put in place a synchronization.

What is an embedded entity?

Main objects (like project, job or companies) have a lot of foreign keys and it can be a huge work to fill each of them.
Let's take for example the object job (JobType,JobPriority,Project) or project (ProjectType,ProjectStatus,Company).

Instead of making a lot of API calls for each of the foreign keys, you can directly define the "foreign object".
This "entity" is embedded in the main entity.

Example

<task>
    <name>test task</name>
    <description>replace the light of the lift which is broken</description>
    <task_type>
        <code>0001</code>
        <name>internal task</name>
    </task_type>
</task>

What will happen, is that the API will do the following work for you, when trying to add this task

It will:

• Check if the task_type_id (Guid) is there. If not, it checks if a node "task_type" exists
• Verify if there is already a task_type in the system with the provided key (0001)
• If not found, the API will add the task_type in the system
• THEN Add the newly created task_type_id (Guid) property to the return message.
• If task_type was found, verify if the properties filled on the embedded entity (like task_type.name) changes. If yes, update the embedded entity
• THEN replace the task_type_id (Guid) property to the return message
• Add the task in the system

As you can see, the number of actions executed on the database are not small. It means it has an impact on the speed of the API Response. Depending on the integration, you can uses them or not

Embedded Code

If you are sure that the object already exists in the database, you can also specify only the "code" of the object.
Example

<task>
    <name>Test Task</name>
    <description>Replace the light of the lift which is broken</description>
    <task_type_code>0001</task_type_code>
</task>

Who should use it and why

Integrators that want to link an application with Odyssee need to synchronize a lot of objects.
But some of these objects have no real logic, they are more "admin" objects. For them you can use this concept.
Bigger objects can also be used (like project, or company) but it depends on the context.
It's true that the size of each message will be bigger. But the advantage is that communication between the API and the database will really be fast.

When should you NOT use them

The disadvantage is about the speed. If you are using the embedded entity on an object that are not updated often it means you are sending data and request execution of queries on the online database for nothing.
Depending on the object size and the number of items that will be synchronized, sometimes it's better to not use embedded entities

There is also something else :
Imagine that you want to synchronize your ERP with Odyssee and that the company, project and jobs are created on your system.
But the jobs should be proceeded on Odyssee (Plan it, work on it, put timesheets and parts)
It sounds great with embedded entities, with one single call you can push everything starting with the jobs.
jobs.project_id will be the embedded entity "project".
project.company_id will be the embedded entity "company".

The problem arrives if it should be possible to create also a job on Odyssee.
You will be only able to select "project" that have been already sent as an embedded entity.

Or if you want to have all the companies on Odyssee (CRM/Task or just search).
You will have only the companies that have been sent because used by a project which is used by a jobs.

The power of embedded entites

The following example is ONE single request that can be sent to the API.
This one can be used to import Work Orders into Odyssee. For example in the case when these work orders are only created on the ERP and the rest (planning,timesheet,material used) will be done on Odyssee.

This single call will in fact handles the following tables :

• Work Order Level: jobs, job_type, job_priority, skill
• Project Level : project, equipment_family, project_status
• Company Level : company, company_type, sales_territories, sales_organization

Yes, the main object (jobs) and 10 tables, in one single call.

<jobs>
    <reference_back_office>JOB-124</reference_back_office>
    <description>This is my job description</description>
    <estimated_time>45</estimated_time>
    <internal_memo>Cross-selling : customer is maybe interested by new pump 123</internal_memo>
    <job_status_code>ToBePlanned</job_status_code>
    <date_reported_by_company>2015-06-15T12:16:40Z</date_reported_by_company>
    <job_type>
        <code>REPAIR</code>
        <name>Repair Intervention</name>
	</job_type>
    <job_priority>
        <code>NORMAL</code>
        <name>Normal Priority</name>
	</job_priority>
    <skill>
        <code>AIRCOOLING</code>
        <name>Air Cooling Stuff</name>
	</skill>
    <name>Intevention CEO Office 15h33</name>
    <prejob_information>Call the CEO 30 min before</prejob_information>
    <project>
        <reference_back_office>PRJ-ODS-1</reference_back_office>
        <name>Air cooling headquarters</name>
        <description>Full system of air cooling</description>
        <shutdown_consequence>NO air cooling for CEO</shutdown_consequence>
        <equipment_family>
            <code>AIRCOOL_123</code>
            <name>AirCooling 123</name>
        </equipment_family>
        <project_status>
            <code>PROD</code>
            <name>Production</name>
            <is_closed>false</is_closed>
        </project_status>
        <serial_number>123-456 15h33</serial_number>
        <company>
            <code>ODS</code>
            <name>Odyssee Mobile</name>
            <email>info@odysseemobile.com</email>
            <phone>+32 2 513 48 19</phone>
            <sales_organization_code>DEFAULT</sales_organization_code>
            <db_language_code>NL</db_language_code>
            <company_type>
                <name>SA/NV</name>
            </company_type>
            <street>Stalingradlaan</street>
            <street_number>100</street_number>
            <zip>1000</zip>
            <city>Brussels</city>
            <db_country_code>BE</db_country_code>
            <sales_territory>
                <code>BRUSSELS</code>
                <description>Brussels</description>
                <sales_organization_code>DEFAULT</sales_organization_code>
			</sales_territory>
		</company>
	</project>
</jobs>