Link your ERP

The main goal of this API is to give the opportunity to integrators to link their ERP with Odyssee.

We do our best to give them all the tools, documenations, methods and examples to achieve this link without the need of Odyssee Support.

Should you be lost or unable to do something, feel free to contact our support.

Why link with the API ?

Top of page

Odyssee is a standalone solution to handle mobile service and sales teams. If you already have an ERP system in place, used by your back office people, the real power is to make the link between this system and Odyssee. In this case, your ERP will be used to feed Odyssee with a lot of field team relevant data and depending on your needs, some data will be generated inside Odyssee and exported back to your ERP.

Contrary to exchanging data between system using a manual export/import (csv,xml), which is time consuming and your users won't always have up to date data, using the Odyssee API will automate this step and allow you to be in full control of how you make the integration.

What can you except ?

Top of page

It all depends on your needs !

The API has been built to offer you the possibility to have a "near" real time synchronization. You create a new customer on your ERP, a few seconds later it's available on Odyssee. You complete a Work order on Odyssee, a few seconds later you have the invoice generated in your back office.

Architecture

Top of page

Before going in depth, let's take a look at a few concepts that will be usefull to you:

Entities (tables) have always a primary key (PK), called id, of the GUID (Globally Unique Identifier) type. These values can be filled if your ERP is also using GUID's as PK's.
Foreign keys are built as follows: name of the originating table + id (like project.project_status_id).
There are no null values on the database, all fields have a default value (boolean=false,numeric=0,datetime=1980-1-1).
The Major tables (like project,company,jobs approval) contain a date-time field (modified_dateutc) that you can use to collect new/updated data.
Required fields or constraints are included in the documentation.

Make sure you read all the documentation of the API (authentification, error and return values,embedded entities..) as it will clarify a lot and minimize unnecessary contacts with our support.

Try to make as few calls (Adding, Updating,Listing, Get) as possible and use the Reference part of the API to have more info about the entities.

How to proceed ?

Top of page

Making a link between 2 systems is not easy. If you divide the work in small tasks, it will be easier.

The best way is to define which data needs to be exchanged between the ERP and Odyssee. Depending on how Odyssee is used, different data will be required.

To illustrate this let's take the example of the following Service Integration:

In this example, the ERP manages a lot (invoicing,clients,projects,articles) but the work orders are currently done with paper and manually input later on in the ERP. The idea is to do this part using Odyssee (managing the work orders, plan them, technicians work on them). The output of the work order (Parts Used, Invoicable Time and remarks) will be imported to the ERP where invoices will be generated.

To set this up the following data transfers are required:

Data imported to Odyssee:

user (code,username,firstname,lastname)
company (code,name,vat,phone,email,street,zip,city,country)
project (code,name,company_code,project_type_code)
article (code,description,price,category_code)

Examples of some admin objects:

article categories (code,name)
project types (code,name)

Data exported to ERP:

Materials Used
Invoicable timesheets

Import to Odyssee

Top of page

Take the data from your ERP and send it to Odyssee to create/update objects.

You can do that in different ways:

PUSH : Alter your screens/logic/webservice

In this case, as soon as something happens on the entity in your ERP, the logic will be altered to include a PUSH API to Odyssee to apply the same changes.

The big advantage : it's very fast and you can show to the end user any error messages if API reject the changes.

PULL : Using new process and schedule

In this optic, you don't alter your ERP. You will create a specific process that will handle the synchronization to Odyssee.
It means that on a time base (scheduled task), your process will start and collect information in your ERP that needs to be sent to Odyssee.

How to know something has been changed/updated? By adding a DateTime field (like last_modification) on the tables you want to track, auto filled by a GETUTCDATE() on an SQL Trigger or the stored procedure. Your process only needs to record the last highest last_modification date.

BE AWARE: it's possible that a modification on your ERP has no influence on Odyssee item (for example if the updated field is not synchronized with Odyssee!).

To counter this you can store somewhere the content of the object when you PUSH it to the Odyssee API. Before the next update, you can verify with your internal historic that at least one property synchronized to Odyssee has been changed.

When adding an object to Odyssee, the API will return the id of the generated object (Primary Key, Guid type).
The best is to store it in your ERP.

That way you will avoid a unnecessary GET (List Filter code=%your ERP PK%) to retrieve the id of the object that needs to be updated before doing an UPDATE.

You have also to decide if you will send to Odyssee ALL objects or only used objects (using embedded entities)

Export data from Odyssee to the ERP

Top of page

In this topic you will ask the API if new data is available (updated or created). If yes, you will request linked data and proceed them to your ERP.

BE AWARE that this is a PULL call, because data ready are available using the API but it's not the Odyssee API that will notify you.

The correct way to grab new/updated data from Odyssee is by using the modified_dateutc field.
This field is updated with a GetUTCDate each time the record is touched (Add/Update).

Making a call to List all entities "created or updated" after a specific date is not huge in ressources if started often like each seconds
For example, to export to your ERP the "output" of a Work order when it is completed (no intermediate approvals):

Store on your ERP the highest date_utc already processed (if null then use a value in the past)
Make a call to Odyssee API, using controller JobApproval, using odata: modified_dateutc > %savedValues% and is_daily_approval=false , order by modified_dateutc ASC

api/JobApproval?$filter=modified_dateutc+gt+'2015-07-14T13:08:00.000Z'+and+is_daily_approval+eq+false&$orderby=modified_dateutc+asc

{
  "@odata.context":"https://developers.odysseemobile.com/api/$metadata#JobApproval","value":[
    {
        "id":"4eac58fa-270d-438d-8a2c-2076e48afed4"
        ,"jobs_id":"dbed4bf9-f928-47f1-947f-d6b070443033"
        ,...
        ,"is_daily_approval":false
        ,"contact_name":""
        ,"customer_remarks":""
        ,"date_generated":"2015-07-14T15:19:37Z"
        ,"job_status_id":"6557b9dc-6106-4327-8e26-6f24d0329c33"
        ,"modified_dateutc":"2015-07-14T13:20:07Z"
    }
  ]}

If you have not stored the PK Guid of the jobs when added it on Odyssee, you need to make an additional jobs GET to find back your reference_back_office (your PK) based on job_approval.jobs_id

api/Jobs?$select=reference_back_office&$filter=id+eq+dbed4bf9-f928-47f1-947f-d6b070443033

{
  "@odata.context":"https://developers.odysseemobile.com/api/$metadata#Jobs(reference_back_office)","value":[
    {
      "reference_back_office":"ERP_PK_123"
    }
  ]
}

Now you need to grab all the used parts that belong to this Work Order : controller JobPartUsage, odata jobs_id=%jobsId%

api/JobPartUsage?$filter=jobs_id+eq+dbed4bf9-f928-47f1-947f-d6b070443033

Same for Invoiceable timesheets : controller JobNonPartUsage, odata jobs_id=%jobsId%

api/JobNonPartUsage?$filter=jobs_id+eq+dbed4bf9-f928-47f1-947f-d6b070443033

As soon as you proceed one job approval object, store his job_approval.modified_dateutc on your cache for the next call

Job Approval PDF

Top of page

The Job approval PDF (entity db_file) is a bit different that the other entities because the PDF are generated based on a queue system.
It means the PDF can be generated few seconds after the job is completed .. or 15 min .. or 2 hours after.

(You can find all the information about entity db_file on the Help \ Advanced \ Files section.)

It means you need to make an extra call to the files to see if one need to be downloaded.

JobApprovalPDF are files linked to the job_approval. You can make a new call on job_approval to retrieve the jobs.reference_back_office.

Let's do it, step by step !

Get the Job Approval PDF created after my last download:
Controller DbFile using Odata modified_dateutc > %savedValues% and file_type_name=JOB_APPROVAL and db_table_name=job_approval, order by modified_dateutc desc

api/DbFile?$select=id,id_in_table,file_name
&$filter=modified_dateutc+gt+'2015-07-14T13:08:00.000Z'+and+file_type_name+eq+'JOB_APPROVAL'+and+db_table_name+eq+'job_approval'
&$orderby=modified_dateutc+asc

Result

{
  "@odata.context":"https://developers.odysseemobile.com/api/$metadata#DbFile(id,id_in_table,file_name)","value":[
    {
      "id":"c9083c22-7da7-4161-977b-e28aa82f98ea"
    ,"id_in_table":"ce771dc9-cc12-48d2-b46b-8a82ce27a314"
    ,"file_name":"Job #41 TestWOWithReopen 2015-07-14 15.19.37.pdf"
    }
  ]
}}

We have 1 object to proceed and have already the id and file_name.
To Get the content use the following method

api/DbFile/GetFileContent?id=c9083c22-7da7-4161-977b-e28aa82f98ea

Result contains the Content of the file.

Now, you need to know more information about the job approval and on which jobs he is linked too (to find the job_approval.jobs_id or further for jobs.reference_back_office).

api/JobApproval(ce771dc9-cc12-48d2-b46b-8a82ce27a314)

Result

{
  "@odata.context":"https://developers.odysseemobile.com/api/$metadata#JobApproval/$entity"
    ,"id":"ce771dc9-cc12-48d2-b46b-8a82ce27a314"
    ,"jobs_id":"453c813e-7220-4f7d-b318-7b6db78c007f"
    ,...
    ,"date_generated":"2015-08-28T13:20:25.060Z"
    ,...
}

If you have enough with the job_approval.jobs_id, then perfect.
If you need the field jobs.reference_back_office, just make a Get on Jobs based on job_approval.jobs_id found.

api/Jobs(453c813e-7220-4f7d-b318-7b6db78c007f)

Result

{
  "@odata.context":"https://developers.odysseemobile.com/api/$metadata#Jobs/$entity"
    ,"id":"453c813e-7220-4f7d-b318-7b6db78c007f"
    ,"reference_back_office":"MyBackOfficeRef"
    ,...
}

Full Sample Application

Top of page

We develop a sample apps that show how you can synchronize your ERP with Odyssee.
This apps, in C#, is documented and you can use it has a base to start your project.

Browse the Odyssee API Sample help page for more information

Odyssee Mobile

API User Guide

Link your ERP

Contents :

Why link with the API ?

What can you except ?

Architecture

How to proceed ?

Import to Odyssee

Export data from Odyssee to the ERP

Job Approval PDF

Full Sample Application