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.
All examples assume that you have been authenticated.
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 orderobj_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, useoffset=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
andrevision
.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 isYYYY-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. 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
Value Description Example has_more
Indicates whether more records exist: true or false. false
obj_type
The type of object being queried 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. Advertiser #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
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×tamp>=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×tamp>=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×tamp>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