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.

Examples:

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 group requests and send them in sequences

We recommend the following sequence:

1. All actions about hierarchies (create, update, delete)
2. All actions about users (create, update, delete)
3. All actions about memberships (create, update, delete)

When using multiple threads, be very careful about sequence. E.g. in case of a hierarchy that depends on a parent which is handled by another thread.

To speed up membership operations, you can include the following request header for all membership related operations:

"AllowOptimizedOperation"="true" (key is "AllowOptimizedOperation", value is "true" )

This will cause our servers to use a cached version of the hierarchy structure when performing membership operations. Currently the servers will cache the structure for 10 minutes, as long as that header is provided.


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.

  • In contrast to IMS Enterprise XML, with Enterprise Services you will need to do explicit delete requests


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.