Link Search Menu Expand Document

PDF

Working with History

Platform API

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.

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

    ValueDescription
    sortSorts 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_typeSpecifies the object type. For example: obj_type='ad'.
    offset=mSpecifies 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=nReturns the most recent n history records.
    revisionSpecifies a revision number. For example, to return one history record, use the obj_id and revision.
    timestampUse 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_idSpecifies 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.
    userSpecifies 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
    [{
    "uid": "60061321-c001-fff1-8123-b0769b",
    "primary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
    "id": "1611010849",
    "modified_date": "2016-01-21 23:08:39",
    "sales_lead_id": "1610857649",
    "primary_trafficker_id": "1610857649",
    "secondary_trafficker_id": "1610857649",
    "budget_pacing": "soft_budget",
    "primary_analyst_id": "1610857649",
    "type": "order",
    "start_date": "2016-01-21 08:00:00",
    "revision": 1,
    "status": "Pending",
    "account_id": "1611310336",
    "end_date": null,
    "deleted": "0",
    "created_date": "2016-01-21 23:08:39",
    "click_through_window": "86400",
    "sales_lead_uid": "6003bcb1-acc0-fff1-8123-b0769b",
    "primary_analyst_uid": "6003bcb1-acc0-fff1-8123-b0769b",
    "single_ad_limitation": "0",
    "instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
    "view_through_window": "86400",
    "name": "John Advertiser #1 Order #1",
    "notes": "",
    "budget": "1000.00",
    "account_uid": "600aa500-accf-fff1-8123-b0769b",
    "v": "3",
    "external_id": "",
    "secondary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b"
}]

    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

    ValueDescriptionExample
    has_moreIndicates whether more records exist: true or false.false
    obj_typeThe type of object being queried for history.order
    obj_idThe ID associated of the object.1611010849
    ipIP address.10.0.50.56
    reasonThe reason or method of modification.api
    first_nameThe user’s first name.John
    last_nameThe user’s last name.Advertiser #1
    nameThe user’s first and last name.John Advertiser #1
    emailThe user’s email address. This is used to identify the person who modified an object.john.smith+i59\_adv1\@openx.com
    timestampThe date and time that the object was modified.2016-01-21 23:08:39
    actionThe action that was performed to the object.create
    real_userThe real user’s email address.john.smith+i59\_adv1\@openx.com
    typeThe type of object query.audittrail
    account_uidThe account uid for the associated object.600aa500-accf-fff1-8123-b0769b
    instance_uidThe platform_hash of the session.af2fd08d-7186-4d75-9a06-61d83cb0769b
    revisionThe revision number of the object.1
    limitThe maximum number of records to return.30
    offsetThe distance (displacement) from the beginning of the object until a given element.0

Samples

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.

In addition, the 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 GET samples return the history of changes for order number 1611010849. The default settings are: limit=20 sort=-revision.

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
Sample response
{
	"has_more": false,
	"objects": [{
		"obj_type": "order",
		"changes": {
			"new_value": {
				"uid": "60061321-c001-fff1-8123-b0769b",
				"primary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"id": "1611010849",
				"modified_date": "2016-01-21 23:08:39",
				"sales_lead_id": "1610857649",
				"primary_trafficker_id": "1610857649",
				"secondary_trafficker_id": "1610857649",
				"budget_pacing": "soft_budget",
				"primary_analyst_id": "1610857649",
				"type": "order",
				"start_date": "2016-01-21 08:00:00",
				"revision": 1,
				"status": "Pending",
				"account_id": "1611310336",
				"end_date": null,
				"deleted": "0",
				"v": "3",
				"click_through_window": "86400",
				"sales_lead_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"primary_analyst_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"single_ad_limitation": "0",
				"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
				"view_through_window": "86400",
				"name": "John Advertiser #1 Order #1",
				"notes": "",
				"budget": "1000.00",
				"secondary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"created_date": "2016-01-21 23:08:39",
				"external_id": "",
				"account_uid": "600aa500-accf-fff1-8123-b0769b"
			}
		},
		"obj_id": "1611010849",
		"ip": "10.0.50.56",
		"reason": "api",
		"program": [
			"uwsgi"
		],
		"user": {
			"first_name": "John",
			"last_name": "Advertiser #1",
			"name": "John Advertiser #1",
			"email": "john.smith+i59_adv1@openx.com"
		},
		"timestamp": "2016-01-21 23:08:39",
		"action": "create",
		"real_user": "john.smith+i59_adv1@openx.com",
		"type": "audittrail",
		"account_uid": "600aa500-accf-fff1-8123-b0769b",
		"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
		"revision": 1
	}],
	"limit": 20,
	"offset": 0
}

Return history by revision

The following GET samples specify a specific revision (1) in the history.

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
Sample response
{
	"has_more": false,
	"objects": [{
		"obj_type": "order",
		"changes": {
			"new_value": {
				"uid": "60061321-c001-fff1-8123-b0769b",
				"primary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"id": "1611010849",
				"modified_date": "2016-01-21 23:08:39",
				"sales_lead_id": "1610857649",
				"primary_trafficker_id": "1610857649",
				"secondary_trafficker_id": "1610857649",
				"budget_pacing": "soft_budget",
				"primary_analyst_id": "1610857649",
				"type": "order",
				"start_date": "2016-01-21 08:00:00",
				"revision": 1,
				"status": "Pending",
				"account_id": "1611310336",
				"end_date": null,
				"deleted": "0",
				"v": "3",
				"click_through_window": "86400",
				"sales_lead_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"primary_analyst_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"single_ad_limitation": "0",
				"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
				"view_through_window": "86400",
				"name": "John Advertiser #1 Order #1",
				"notes": "",
				"budget": "1000.00",
				"secondary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"created_date": "2016-01-21 23:08:39",
				"external_id": "",
				"account_uid": "600aa500-accf-fff1-8123-b0769b"
			}
		},
		"obj_id": "1611010849",
		"ip": "10.0.50.56",
		"reason": "api",
		"program": [
			"uwsgi"
		],
		"user": {
			"first_name": "John",
			"last_name": "Advertiser #1",
			"name": "John Advertiser #1",
			"email": "john.smith+i59_adv1@openx.com"
		},
		"timestamp": "2016-01-21 23:08:39",
		"action": "create",
		"real_user": "john.smith+i59_adv1@openx.com",
		"type": "audittrail",
		"account_uid": "600aa500-accf-fff1-8123-b0769b",
		"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
		"revision": 1
	}],
	"limit": 20,
	"offset": 0
}

Return history by user

The following GET samples specify 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.

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
Sample response
{
	"has_more": false,
	"objects": [{
		"obj_type": "order",
		"changes": {
			"new_value": {
				"uid": "60061321-c001-fff1-8123-b0769b",
				"primary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"id": "1611010849",
				"modified_date": "2016-01-21 23:08:39",
				"sales_lead_id": "1610857649",
				"primary_trafficker_id": "1610857649",
				"secondary_trafficker_id": "1610857649",
				"budget_pacing": "soft_budget",
				"primary_analyst_id": "1610857649",
				"type": "order",
				"start_date": "2016-01-21 08:00:00",
				"revision": 1,
				"status": "Pending",
				"account_id": "1611310336",
				"end_date": null,
				"deleted": "0",
				"v": "3",
				"click_through_window": "86400",
				"sales_lead_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"primary_analyst_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"single_ad_limitation": "0",
				"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
				"view_through_window": "86400",
				"name": "John Advertiser #1 Order #1",
				"notes": "",
				"budget": "1000.00",
				"secondary_trafficker_uid": "6003bcb1-acc0-fff1-8123-b0769b",
				"created_date": "2016-01-21 23:08:39",
				"external_id": "",
				"account_uid": "600aa500-accf-fff1-8123-b0769b"
			}
		},
		"obj_id": "1611010849",
		"ip": "10.0.50.56",
		"reason": "api",
		"program": [
			"uwsgi"
		],
		"user": {
			"first_name": "John",
			"last_name": "Advertiser #1",
			"name": "John Advertiser #1",
			"email": "john.smith+i59_adv1@openx.com"
		},
		"timestamp": "2016-01-21 23:08:39",
		"action": "create",
		"real_user": "john.smith+i59_adv1@openx.com",
		"type": "audittrail",
		"account_uid": "600aa500-accf-fff1-8123-b0769b",
		"instance_uid": "af2fd08d-7186-4d75-9a06-61d83cb0769b",
		"revision": 1
	}],
	"limit": 30,
	"offset": 0
}

Additional Samples

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.

Return all history for an object

The following GET 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.

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 GET sample returns one history record for the specified object id and the specified revision.

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 GET sample returns all history records for the specified object id that were modified by the specified user (indicated by the email address).

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 GET sample returns all history records for the specified object id, with a timestamp greater than (>) a specified date.

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 GET sample returns all history records for the specified object id, with a limit of 30 and an offset of 10.

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 GET sample returns all history records for the specified object id, with a limit of 30 and an offset of 10, sorted by timestamp (descending).

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