You are here: Developers > OpenX Platform API > Use Cases > Working with history

Working with history

You can get history information associated with an object by making a GET request to the OpenX Server. For more information about the history feature, see History.

Note: All examples assume that you have been authenticated.

  1. From the terminal window on your system, make the following GET request to the OpenX server (in this case, an order):

    curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?obj_type=order&obj_id=1611010849'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

    The values listed in the table below are available for the GET request to the OpenX server.

    History values

    Value Description
    sort Sorts the output by revision. Options:
    • sort=revision: Returns search results by revision in ascending order
    • sort=-revision: Returns search results by revision in descending order
    obj_type Specifies the object type. For example: obj_type='ad'.
    offset=m Specifies an offset value for a history record search. For example, to bypass the first ten records and start searching at the eleventh record, use "offset=10". To return the second ten records, use "offset=10 limit 10".
    limit=n Returns the most recent n history records.
    revision Specifies a revision number. For example, to return one history record, use the obj_id and revision.
    timestamp Use timestamp to return history information for an object based on a date or date range. For example, use timestamp > or timestamp < to specify history after or before a specific date. Operators include >, <, =, >=, <=, and !=. timestamp format is YYYY-MM-DD.
    obj_id Specifies an object's id. When just an object id is specified, returns all parsed history records for the specified object revision, displaying the most recent first.
    user Specifies the user, indicated by an email address, who made a modification to an object.
  2. The OpenX server processes the GET request and returns a list of all history information for the specified order object. An example of history is shown below.

    The values listed in the table below are some of the values returned in the response output from the OpenX server. Some values depend on which object type was queried.

    GET History Response Values

    Value

    Description

    Example

    has_more Indicates whether more records exist: true or false. false
    obj_type The type of object being quered for history. order
    obj_id The ID associated of the object. 1611010849
    ip IP address. 10.0.50.56
    reason The reason or method of modification. api
    first_name The user's first name. John
    last_name The user's last name. AdvertiserIn OpenX, an account type that represents a business that runs advertising campaigns to display ads on websites. #1
    name The user's first and last name. John Advertiser #1
    email The user's email address. This is used to identify the person who modified an object. john.smith+i59_adv1@openx.com
    timestamp The date and time that the object was modified. 2016-01-21 23:08:39
    action The action that was performed to the object. create
    real_user The real user's email address. john.smith+i59_adv1@openx.com
    type The type of object query. audittrail
    account_uid The account_uid for the associated object. 600aa500-accf-fff1-8123-b0769b
    instance_uid The platform_hash of the session. af2fd08d-7186-4d75-9a06-61d83cb0769b
    revision The revision number of the object. 1
    limit The maximum number of records to return. 30
    offset The distance (displacement) from the beginning of the object until a given element. 0

Samples

Note: The following samples show both ways to create a history call:

  • specify an object type and specific object (obj_id) and then append history (audittrail) parameters
  • query the history (audittrail) endpoint and pass in the object type, object id, and additional parameters

Note: Also, the following samples show the abbreviated form of the GET call as opposed to a full curl call.

Return object history with limit and sort

The following sample returns the history of changes for order number 1611010849. The default settings are: "limit=20 sort=-revision".

GET Request

Object id first; history parameters second

http://server_name.openx.net/ox/4.0/order/1611010849/audittrail

History (audittrail) object first; object id second

http://server_name.openx.net/ox/4.0/audittrail?obj_type=order&obj_id=1611010849

Return history by revision

The following sample specifies a specific revision (1) in the history.

GET Request

Object id first; history parameters second

http://server_name.openx.net/ox/4.0/order/1611010849/audittrail?revision=1

History (audittrail) object first; object id second

http://server_name.openx.net/ox/4.0/audittrail?obj_type=order&obj_id=1611010849&revision=1

Return history by user

The following sample specifies more filters including "user" which is an email address. Note that the email value "john.smith+i59_adv1@openx.com" must be url-encoded because the plus sign (+) has a special meaning (space) in URLs. Therefore, it must be encoded as %2b.

GET Request

Object id first; history parameters second

http://server_name.openx.net/ox/4.0/order/1611010849/audittrail?limit=30&timestamp>=2016-01-21&user=john.smith+2bi59_adv1@openx.com

History (audittrail) object first; object id second

http://server_name.openx.net/ox/4.0/audittrail?obj_type=order&obj_id=1611010849&limit=30&timestamp>=2016-01-21&user=john.smith+2bi59_adv1@openx.com

Additional Samples

Note: The following samples show only the second way to create a history call (by querying the history (audittrail) endpoint and passing in the object type, object id, and additional parameters).

Note: The following samples show the full curl call.

Return all history for an object

The following sample returns all history records for the specified object id. If more than ten records exist in the database, it returns the most recent ten. To return more than ten records, use limit=int.

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Return history for a specified revision

The following sample returns one history record for the specified object id and the specified revision.

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id&revision=integer'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Return history modified by a specified user

The following sample returns all history records for the specified object id that were modified by the specified user (indicated by the email address).

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id&user=email_address'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Return object history after a specified date

The following sample returns all history records for the specified object id, with a timestamp greater than (>) a specified date.

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id&timestamp>2016-01-01'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Return object history with offset and limit

The following sample returns all history records for the specified object id, with a limit of 30 and an offset of 10.

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id&limit=30&offset=10'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Return object history with offset, limit, and sort

The following sample returns all history records for the specified object id, with a limit of 30 and an offset of 10, sorted by timestamp (descending).

GET Request

curl -v -X GET 'http://server_name.openx.net/ox/4.0/audittrail?&obj_id=object_id&limit=30&offset=10&sort=-timestamp'  -H "Content-Type:application/json"--cookie $COOKIE | python -mjson.tool

Feedback form