Dos and don'ts for itslearning IMS ES clients

In the following text, “operations” and objects are defined as:

Operations = The Product of # of threads and # of objects per request

Objects are the single person, group or member* elements that will be created, updated or deleted.

*Memberships have multiple member objects. Each member, not membership, equals one operation in this regard.


4 threads of createPersons requests with 5 person objects per request = 20 operations.

1 thread of updatePersons with 5 person objects in each + 1 thread of deleteMembership with 5 members per request = 10 operations.

Do build a nice and fault tolerant client that adheres to this simple process (multiple threads possible):

  1. Send your request containing a low number of operations.

  2. Wait for the message to be processed by itslearning.

    1. If an error occurs because of incorrect data, correct your data and resubmit.

    2. If an error occurs on the server side, delay resending the request, while increasing the wait for each successive error.

  3. Repeat

Do balance the number of threads vs number of objects in each request.

  • A request containing several operations will take longer to process than a request with a single object, and will also increase the complexity of error handling on the client side.

  • On the other hand, using only requests with a single object will increase the total latency.

  • Itslearning suggests that the total number of unprocessed operations at any given time should be <10 (ten)

  • As of October 2012, itslearning strongly discourages large batches of >50 operations

Do prepare for error handling!

  • Likely scenarios are data format errors or declined requests to high load on server.

  • Before resubmitting the request, correct any formatting errors.

  • If the server was unable to service your request, please wait a little before resubmitting so itslearning can clear the queue or fix any interruption on the server side.

    • We suggest increasing the delay gradually for each unsuccessful request

    • For example: 10 secs for the first error, 20 sec for the second, 60 for the third, 600 sec for the fourth

Do control dependencies between objects and threads, so that a new request does not contain objects that rely on objects in an unanswered or unsuccessful request.

Do keep a local filter database, so that only changed objects are submitted to itslearning.

  • Running a full “resync” should also be possible in the client, but this will inevitably take a long time to complete and should only be done when absolutely necessary.

Don’t schedule large updates during your own peak hours.

Don’t request large amounts of data at one time, for example avoid requesting all members from the top level hierarchy on a regular basis.

Do provide a unique messageIdentifier for each SOAP request submitted,. This makes it easier to search logs and scan for errors in the event that anything goes wrong.

Do ask for as little as you need, as rarely as you can.

These guidelines may be updated from time to time as the service evolves, so it is good practice to check back here at regular intervals.