Introduction to Tizra account event logging

The Acccount update interface allows a Tizra server to notify a customer system of certain events that take place on the Tizra server relating to user accounting and e-Commerce.

This is based on encrypted connections from the Tizra server to a remote web server that accepts updates on Tizra server events. The Tizra server will post updates to the remote web server as needed. Events will be queued and reposted in case of errors until a retry limit is reached. The remote server will accept updates at a URL which will be configured into the Tizra web site.

Messages are sent via PUT to a single service URL, and are in JSON format. The JSON formats described here are very similar to the general Tizra JSON Interface.

Authentication

Authentication is via Tizra administrative API tokens.

Data model

The following are a few notes on the data models that are behind Tizra commerce and that are realized in the JSON records.

The tizra-id is the database UID for any item in the Tizra system. So each record or subrecord that has a tizra-id is an object on our database.

A User gets access to an Object, because they have a License which links a (User,Object) pair to a Termsheet (a description of the access control rules that limit that User's access to that Object). A user gets a License in a few ways, but the in this case by making a purchase described by an Offer. An Offer specifies the Termsheet for the license the user will get once the offer is purchased (or accepted for free). That offer may be restricted to different user groups, etc. (It's also possible for people to get Licenses by being assigned one by an administrator, or based on their membership in a Group, as determined by a boolean test on the AdminTags associated with an account).

Extra fields can be expected

Tizra JSON records are built on a general data facility, and may expose additional fields not documented here. These extra fields may be ignored, and other extra fields may appear at a later time. The "props" section of Offers and Users holds properties defined in Tizra content management, and can be reconfigured at any time. Non-props fields are more wired into the system back end, and are less likely to change. It's worth noting that tizra-ids are strings, and not numbers.

Operations

account property update

This is essentially a user record, with the field event added to it.

Note: Tizra will PUT a record with (at least) the following fields. Extra fields may be ignored.

{
        "event": "account-update",
        "tizra-id":"Id of the account",
        "email":"[email protected]",
        "props":{
                "FirstName":"david",
                "LastName":"durand",
                "Some account property": "sub1;sub2;sub3",
                ...
         },
         ... other properties, as system is extended.
            Expect that other fields may show up here (generally you should ignore them,
            and in any case do not count on their presence or meaning
             unless they are documented.
}

create an account

This is essentially identical to the update operation, but notes that an account did not previously exist in the Tizra system.

Note: Tizra will PUT a record with (at least) the following fields. Extra fields may be ignored.

{
        "event": "account-create",
        "tizra-id": "Id of the account",
        "email":"[email protected]",
        "props":{
                "FirstName":"david",
                "LastName":"durand",
                "Some account property": "sub1;sub2;sub3",
                ...
         },
         ... other properties, as system is extended.
            Expect that other fields may show up here (generally you should ignore them,
            and in any case do not count on their presence or meaning
             unless they are documented.
}

purchase

Note: Tizra will PUT a record with (at least) the following fields. Extra fields may be ignored.

{     "event" : "purchase",
      "tizra-id": "some string",
      "user":    { ... as in account-update minus the "event" field ... },
      "total": float,
      "currency-code": "USD",
      "items" : [
           {   "tizra-id": "232kj",
               "name": "",
               "props": {
                       "product-code": "",
                       ... potentially other properties ...
                },

                "offer-id": "tizra-id",
                "price": float,
                "currency-code": "USD",
                "license-id": integer
                  ... perhaps others ...
           }, 
           { other purchases in same transaction} ...,
           { If taxes were charged, they will be treated as special items, with the a unique name
              and product code identifying the specific type of tax }

      ],
}

The purchase operation includes a product-code property in the item record. This is available for synchronization with the external agent's product-code database. The product code is filled in based on the Offer under which a purchase was made, or based on product that was purchased, in that order of priority. So if the Offer has a productCode property, that is the value that will be used in the purchase record. If the Offer does not have an associated productCode then the value of the productCode property on the purchased content will be used instead. If neither of these two properties are present, a unique tizra-assigned product code string will be used, composed of the TizraId of the item sold, a hyphen, and the TizraId of the offer.

In planning a commerce integration with a separate data management engine, the first decision to be made is whether the Tizra product database is the authoritative source for product identities, or whether that is at the external database. Where the many offers or remixed products are being managed, we recommend that Tizra's database be the primary source for product identifiers. This is the easiest scenario:

• no productCode properties are defined
• Tizra will create identifiers for all distinct purchasable items.

When Tizra is not controlling the identifiers, product codes should be used. If the terms of sale for each distinct unit of content are the same, product codes should be assigned to content. If the same content can be sold with different access control rules at different price points, or to different audiences at different price points, then the productCode should be attached to the various Offers.

Because each purchase will have just one product code, care is required if you need to mix product codes on both Offers and on content.

Operation responses

HTTP response codes should be used to signal errors, according to the standard. If a success code is returned, the notification is deemed to have succeeded, and the notification will no longer be retained at Tizra. Notifications that produce errors are retained, which is useful for debugging and recovery.

Currently, HTTP result code processing works like this:

• 200 (actually any 2XX code) Success. The information will be marked as transmitted at the Tizra end, and the operation will not be retried
• 3XX Redirects will not be accommodated for this interface, and will be treated as a fatal error and not retried.
• 400 bad syntax. The request cannot even be parsed properly, and retrying won't help. This can be used for any non-retryable error. In general, 400 errors should be used when retrying won't help.
• 406 bad semantics. The request is not valid, and retrying won't help.
• 401 Additional authentication over the SSL channel may be supported at some future time. If such support were added, this would become the only 4XX code on which the Tizra server might retry an operation.
• 503 or 500 or will indicate an operation failure, and the content of the message-body will be the error message. 500 should be used for errors when retrying may work at a later time. For instance, if a correctly-formed request refers to an unknown user or product, there may be some inconsistency between the Tizra's database and the external one. The same request might well complete properly once the databases are in sync.