Other useful information

This page contains information which may be useful when implementing a full app, or when using the API to synchronize data with Microbizz.

See also /wiki/spaces/DEV/pages/29033638

Synchronization

You will often want to maintain up-to-date list of the most important objects, like customers, tasks, persons, equipments etc. That way you can lookup details of eg. a customer instantly, without having to communicate with the Microbizz server. This is usually called 'synchronization', and requires that you call eg. GetCustomersByLastChange regularly, eg. every 10 minutes or 1/2 hour or whatever you find reasonable.

API calls whose name end in …ByLastChange require that you specify the date+time of the last time you call the API call. The API call then returns all the objects that have changed since then.

The API calls may return a 'resumekey' value. This indicates that the call didn't return all the objects that have changed. You should then call the same API call again, with the same date+time and also specify the resumekey value that you just received. Repeat this until the API call no longer returns a resumekey value. The API call will return date+time of when Microbizz received the request. This should be used as date+time the next time you synchronize.

F.ex.:

getcustomersbylastchange_date = '1970-01-01'
getcustomersbylastchange_time = '00:00:00'

function synccustomers()
  resumekey = false
  do
    data = GetCustomersByLastChange(getcustomersbylastchange_date, getcustomersbylastchange_time, resumekey)
    if (data.resumekey)   resumekey = data.resumekey
  while (data.resumekey)
  // remember date+time for next time 
  getcustomersbylastchange_date = data.date
  getcustomersbylastchange_time = data.time
endfunction

Complex types that are objects

The following complex types are objects that should preferably be available when an app is offline. Other complex types (like budgetarea, eventtype, mainpagebox, persontype and many more) are considered part of the setup of Microbizz and need only be read during synchronization. Typically the offline objects are those that the app may send to Microbizz, whereas the remaining objects are only read by the app.

call, customer, directorderline, event, depotorderline, document, feature, invoiceline, message, tmessage, mbmessage, note, partuse, person, prodplanentry, product, registrationentry, salescontact, salescontractline, todo, todoitem, tool, thread, unit, user

Which objects are sent to the app (the "Limit objects..." setting)

Notice that there may be a difference between what is sent to the app, and what the user can access in the app. Just because a task is sent to the app doesn't necessarily mean that the user can see or edit the task. F.ex. if the user doesn't have access to a task, then the app may still receive the task so that it can display the name of the task in certain situations, but the user will not be able to access the task.

There is a setting in Microbizz called “Limit which objects are available in the app” which reduces the number of objects sent to the app. The behavious depends on the type of object.

For the new app this settings is assumed to be ON when reading tasks.

Without the setting

Tasks

All tasks except those that were closed more than 2 weeks ago.

Customers

All customers that aren't deactivated.

Persons

All persons.

Equipment

All equipment that aren't deactivated.

With the setting

For persons and customers this is the same as without the setting.

Tasks

Tasks that fulfill any of these criteria:

1. belongs to a pool which belongs to one of the user's teams

2. user is responsible or is an additional user or is in a “user” custom field

3. belongs to one of the user's teams

4. is planned to the user within +/- one month from now

but not if the task fulfills any of these criteria:

1. was last changed more than a year ago

2. “next action” is more than a month away (in the past or future)

Equipment

Old app

The old app reads all equipment that isn't deactivated.

New app

The new app only reads equipment that isn't deactivated and that do not have a “place of home”.

When accessing the equipment list of a task or customer, the new app reads all equipment that are relevant for that task/customer.

Notice

The app may specify that closed objects (tasks/customers/etc) should be ignored, in which case no closed task or deactivated customer or inactive user etc. is included.

Discussion of synchronization

The initial configuration and subsequent synchronization requires reading a lot of data from the Microbizz server. On this page we try to describe an efficient way of doing this, and describe which data to read, which API calls to call.

Often there are multiple ways of reading the data, f.ex. you may either

A) read all hour registrations using GetRegistrationsByLastChange during the synchronization, or

B) read the registrations using GetRegistrationByDate whenever you need to access the registrations.

A) means that all registrations are available to the app all the time, but it slows down synchronization. B) means faster synchronization, but it slows down access to the tasks that need to display summary of registrations.

Generel details about synchronization

Order

It is often a good idea to read certain data before other certain other data, f.ex. it might be a good idea to call GetCustomFields before GetTodosByLastChange, GetCustomersByLastChange etc. as GetCustomFields describes what fields will be available in objects returned by the other calls.

The current app (the one from 2015-2019) uses this order (more or less):

• GetMobileAppSettings

• GetCustomFields

• GetTodosByLastChange

• GetCustomersByLastChange

• GetPersonsByLastChange

• GetToolsByLastChange

• the other Get…ByLastChange

• GetMyTools

• GetPendingQuestionRequests

• the rest of the calls (see below).

Other data

Besides the various Get…ByLastChange calls it will usually also be desirable to read other types of data when synchronizing, f.ex. the list of task states and equipment states (GetTodoStates, GetToolStates). The current app also calls these API calls during synchronization:

• GetCurrentUserID

• GetCustomFields

• GetMyPendingCalls

• GetMyTools

• GetPendingQuestionRequests

• GetCustomAppLinks

• GetTodoTemplates

• GetPersonalDocuments

• GetToolTypes

• GetWorkareas

• GetGPSConfig

• GetCheckIn

• GetTodoStates

• GetToolStates

• GetProductStates

• GetCheckpoints

• GetInternalRegistrations

• GetPastRegistrations

• GetCustomerTypes

• GetEventTypes

• GetStocks

• GetTeams

• GetToolServiceProtocols

• GetPlannedTodos

• GISGetCustomBaselayers

• GetQuestionForms

• GetPlanDestinations

• GetIcons

• GetColumnGroups

• GetProductUnits

Perhaps these should be read slightly less often than Get…ByLastChange.

The order is not terribly important.

Performance

A full synchronization currently involves more than 50 API calls. Luckily many calls may be combined into a single request, which will speed up things. The Get…ByLastChange calls cannot be combined into a single request.

Initial configuration

The initial configuration (when the user has just entered a XXXX-XXX configuration code) should be slightly different from the normal, regular synchronization. During the initial configuration the Get…ByLastChange calls that support the ignoreclosed parameter should have that parameter set to 1.

ignoreclosed means that Microbizz will skip some objects which it knows are of no use to the app, but which would otherwise be included because they fulfill the criteria for being included. F.ex. a deleted product will be skipped if ignoreclosed is set, as the app doesn't need to know about deleted products. However, the normal synchronization should detect if an existing product has just been deleted so that it can be discarded from the app database, and therefore ignoreclosed should not be set during the normal synchronization.

GetMobileAppSettings should be the first call.

Threads and messages

When reading threads and messages you can either

A) read all threads and messages during the synchronization, or

B) only read the threads and the read the messages whenever the user opens a thread.

Since there can be many thousands of thread, the second solution B) is preferred, if the app allows it. To use B) simply add the parameter exclmessages = 1 to the GetThreadsByLastChange API call. That way you will get only the threads, not the messages for each thread.

Normal synchronization

GetMobileAppSettings should be the first call.

The order of API calls is probably not important, as long as all API calls are executed.

Registrations

Initial config.

During the initiel config. the app should read the last 60 registrations, using GetRegistrationByDate.

Normal sync.

Do nothing.

Other times

When the app wants to display the regs for a task etc it should read the regs. using GetRegistrations.

When displaying list of daily worksheet for a week, the app should read all registrations for that week, using GetRegistrationByDate. Similarly, when displaying the list of previous registrations, the list of 60 days should be reread the same way.

Threads/Notes

Initial config.

GetThreadsByLastChange should be called with the parameter onlysubscriber set to 1 and ignoreclosed set to 1.

Until 2019-11-19 we said that the parameter exclmessages should be set.

Normal sync.

Like the initial config.

Other times

When the app needs to display the threads for an object, it should read them using GetThreads. When the app needs to display the notes in a thread, it should read them using GetThreadByID and set exclmessages to 0.

Messages

Appointments / planning

Initial config.

Read appointments and planning for the previous month and the next month (ie. +/- 30 days) using GetEventsByUserAndDate and GetProductionByUserAndDate.

Normal sync

The app should try to keep the calendar for the next 30 days up to date, by calling GetEventsByUserAndDate and GetProductionByUserAndDate for the date 30 days ahead. This should be done just once a day.

Other times

Use GetEventsByUserAndDate and GetProductionByUserAndDate when displaying the calendar. If a date has been read within the last minute or so then don't read it again.

Tasks

Initial config.

Call GetTodosByLastChange (starting at 1970-01-01 as always) and specify the parameter limitnumobjects set to 1, and ignoreclosed set to 1.

When the Microbizz has returned all the tasks, the startdate should be reset to 1970 and the normal sync should then the started. This way the app will first read the most important tasks, and then read all the tasks in the normal sync.

Normal sync

Just use GetTodosByLastChange, don't specify the parameter limitnumobjects, but specify the parameter ignoreclosed set to 1.

Companies/customers

Just use GetCustomersByLastChange in all situations, specify the parameter ignoreclosed set to 1.

Equipment

GetMobileAppSettings may now return a new 'function' named LimitNumObjects. If this isn't set then the app should just call GetToolsByLastChange (with ignoreclosed=1) during the initial config., and also call GetToolsByLastChange (with ignoreclosed=0) during the normal sync.

If LimitNumObjects is set, then the app should do as described below.

Initial config.

This only applies if LimitNumObjects is set.

Call GetToolsByLastChange with the parameter ignoreclosed set to 1 and the parameter placeofhome set to 2.

GetToolsByLastChange will also return a list of companies for which there may be tools that are also important. The app should read those tools using GetToolsByField, see “Other times” below.

INTERNAL MEMO: Microbizz should detect when the planning for a user is changed and list the affected customers so that they can be returned to the app whenever GetToolsByLastChange is called.

Normal sync

This only applies if LimitNumObjects is set.

At the very least call GetToolsByLastChange with the parameter ignoreclosed set to 1 and the parameter placeofhome set to 2.

GetToolsByLastChange will also return a list of companies for which there may be tools that are also important. The app should read those tools using GetToolsByField, see “Other times” below.

Other times

This only applies if LimitNumObjects is set.

When the user opens the equipment list for a company/customer or for a task/todo then it should read the list of tools for that company or task. If the list of tools has been read within the last minute or so then it is not necessary to read the list again.

For companies use GetToolsByField and specify the parameters field = custref and value = the ID of the company. Possibly specify the knowntools parameter, to reduce the number of tools that need to be read.

For tasks use GetToolsByTodoID. Possibly specify the knowntools parameter, to reduce the number of tools that need to be read.

Products

The initial config. should only the those products that the user is likely to be using the most.

Initial config.

Use GetProductsByLastChange with the parameter onlyfavorites set to 1 and ignoreclosed set to 1.

Normal sync

Use GetProductsByLastChange without the parameter onlyfavorites and without the parameter ignoreclosed.

Product use

Initial config.

The initial config. should not read any product use.

Normal sync

The normal sync. should not read any product use.

Other times

Product use for tasks/todos and tools/equipments should be read when the details about the task or tool is displayed. To read product use for a task, use GetProductUseByTodoID. To read product use for a tool, use GetProductUseByToolID.

Deletion of data

Deleting data in Microbizz may pose a problem for the app. If an object (eg. an equipment) disappears from the Microbizz database, then the object will no longer appear when Microbizz checks to see which objects have changed since last, f.ex. when the apps calls GetToolsByLastChange, because the object simply doesn't exist anymore.

For many object types Microbizz will not delete the object from the database, but will instead set a field to indicate that the object is to be considered deleted. This field is typically called isdeleted, and tells the rest of Microbizz that the object should be ignored, so it will not appear in search results etc. However, the object still exists in the database, and so API calls like GetToolsByLastChange will be able to detect that the object has changed, and will be able to send the object to the app, now with the isdeleted field set.

Notice that the isdeleted field is sometimes used to indicate that the object should not be available in the app for other reasons, f.ex. if a task was closed more than a few das ago.

Also notice that there are "naughty" ways of deleting data in Microbizz, which are only used in special circumstances, and which break all rules. 

Mainpages

Types of boxes

Any object type - Column group

Any object type - Address

Any object type - persons

Any object type - users

Task - Checklist

Task - Reminders

Task - Description

Task - Procedures

Company - Procedures

Company - Subcustomers

Company - Reminders

Person - Companies

Tools - Service

Tools - Take