POST redemption api - Tizra/Tizra-Customer-Tracker GitHub Wiki

Redemption codes have URLs that are based at /admin-api/<site>/redemptions

To create one or more redemption codes, you submit a POST operation, and the result will return the a JSON array of strings, each of which is a single code to be used to redeem content.

Redemption codes are explained in the Tizra manual, but with the introduction of this API, there are a number of new features, so playing with the administrative interface is recommended, until the manual is updated.

A redemption code is represented as a JSON Object which contains a subset of the following fields (depending on the type of access control operation the code respresents).

• access-code This is a string, which will affect access control, usually by emending an account, but also capable of updating privileges only for a single session.

• batch This is an identifying string which is used to group codes in the administration interface, and can be used in any way that is convenient.

• remaining-redemptions Integer count of how many times this code can be redeemed before it becomes invalid. Defaults to 1.

• is-valid Boolean value which is true if the access value can be used. While redemption codes are marked invalid once they have been "used up", their validity can be updated independently if desired

• expiration-date Planned If present, a date after which the redemption code will expire and no longer be valid. The is-valid field is not automatically updated after expiration.

• used-date The last date on which this redemption code was used.

• redeemed-users If present, an array containing a list of the user names of all users that have redeemed this code. If the code is a session code, this will not be present, even if the code has been redeemed, as no account will have been affected by a session code.

• action-type This identifies the type of redemption action taken by this code. Associated with each action type are a number of other fields which are used to execute the action. Possible actions are:

  • add-user-tag Updates the redeeming user account by adding a tag to it. This will affect the user's group memberships, which can affect the visibility, pricing, and access restrictions to content in the system. The tags are identified by the user-tags field.
  • apply-offer Updates the redeeming user account by applying an offer. The result is the same as if the user had completed a purchase using the offer in question. The offer is specified by the access-control-id field which can contain either the tizra-id or the offer number for the particular offer. These are available in the administration UI.
  • session-license Updates the user session of the user by adding a temporary license to the session, with privileges determined by the offer identified in the access-control-id. This is like purchasing the offer, except that the access is limited to a single browser session. This does not require a user to be logged in, or even to have an account, and if they are logged in, it does not permanently change the user's access rights. Sessions are identified by browser cookies, and expire after a period of inactivity by the user. These redemption codes can be used for user sampling, granting limited download access, and the like.
  • apply-offer-match This function works like apply-offer, but rather than applying the offer to the owning object, it will be applied to the objects that match a query specified in the match-specification field of the redemption code. Again, this is just like making a purchase with the offer, but with the purchased object overridden by the match specifications.
  • session-license-match This function is just like session-license, applied to each object that meets the criteria of the match-specification

• match-specification This is a JSON record containing a specification of the objects with access rights that will be affected by application of this redemption code. This record contains 3 fields: all, any, and excluded, which define a search result. All items in this result will have their access rights updated. The meaning of Tizra search parameters in described in POST-search. Note that full searches may contain other parameters, not used by redemption codes.

• access-control-id Specification of the Offer defining the access control rights granted by a code. A string value is used for a Tizra-id, while a numerical value is used for an offer or license number.

• user-tags array of strings, each representing a tag to be added to the user.

A simple redemption code request might look like as follows:

{
	"action-type": "add-user-tag",
	"batch": "test batch",
	"number-of-codes": 10,
	"user-tags": ["member", "institution"]
}

To create 10 codes, the above record would be posted to the remdemption code management endpoint: /admin-api/<site>/redemptions

The result is a JSON array of newly created codes:

["5416ab331fee496e", ...]

A request that applies privileges to specific piece of content might look like this:

{
	"action-type": "apply-offer-match",
        "access-control-id": "2dfe",
	"batch": "test batch",
	"number-of-codes": 10,
	"match-specification" : {
		"all":  [ "ProductId:09238443" ]
	}
}

In this request, we assume that the publisher is using a Tizra property, ProductId, to identify the publication as all or part of a particular salable item managed in another system.

The access control-id can be either an integer object number or the tizra-id of an offer whose terms should be used for the access granted.`

The ability of a license to match more than one object when claimed means that there is a choice between using a collections to represent a multiple publication product, or simply having multiple publication match when the code is redeemed. These two options have different implications when site content changes.

When a license is created it is a connection between a user account and a Tizra object (publication, Collection, etc.). That connection is made once. Later updates to the ProductID properties of publications will not affect past redemptions. This can be handy in the case of new editions, for instance.

A license on a Tizra collection works the same way, but because the contents of the collection can change over time, the specific documents licensed by a collection license may change over time, if the membership of the collection changes.