API Tutorial Lesson 02 - Adding a New User

Managing users requires, as a first step, their registration on our transaction manager. The core of this example consists in a 'UserAdd' transaction, started by the call to the 'UserAddAllow' API and ended by the call to the 'UserAddCommit' API. Remember that error codes always start in ':@Err#': if something goes wrong with the user's registration (for example, he might have been registered already), the call of the 'ErrorDocumentationGet' API at the end of the code will provide us with a text string explaining the reason for the 'UserAdd' transaction having failed.

The 'UserAddAllow' API call requires three blocks of parameters: the first block comprises user's e-mail, name and birth date (used to identify the user), the second block (comprising country and language) allow us to select preferred communication standards for users, while the solution token parameter certifies the solution responsible for the user being added to our cloud-based time-limited transaction manager.

If the call of the 'UserAddAllow' API succeeds (that is, it is possible to add the specified user data as a new user), it returns an operation handle. Note that ALL '…Allow' APIs share this same behavior: their success results in returning the transaction's operation handle. When calling the 'UserAddCommit' API, we have to pass in only this operation handle to confirm the transaction (all other parameters sent to 'UserAddAllow' have already been stored in the pending transaction queue (61), to avoid sending them in twice, which would allow for changes and/or impose a performance penalty).

The 'UserAddCommit' API, as any other '…Commit' API on our cloud-based time-limited transaction manager, returns the same operation handle sent to it in case of success: in other words, the operation handle for the '…Allow' API call is used to identify the whole transaction (however, each additional call receives its own operation handle 'stamp', which is stored in the call log).

It is possible to check if a user is already registered by calling the 'UserValid' API, which requires the solution's token and the user's e-mail address as parameters.

US Patent Requested