The documentation set for this product strives to use bias-free language. For the purposes of this documentation set, bias-free is defined as language that does not imply discrimination based on age, disability, gender, racial identity, ethnic identity, sexual orientation, socioeconomic status, and intersectionality. Exceptions may be present in the documentation due to language that is hardcoded in the user interfaces of the product software, language used based on RFP documentation, or language that is used by a referenced third-party product. Learn more about how Cisco is using Inclusive Language.
To list transactions on the system use the following operation
GET https://<server_address>/api/tool/Transaction/
?hierarchy=[hierarchy]
&format=json
&summary=true
The following query parameter illustrates how a second page of 50 transactions in the transaction log is requested.
skip=50
&limit=50
&hierarchy=[hierarchy]
&format=json
&summary=true
&direction=desc
&order_by=submitted_time
For further information on the query parameters refer to API Parameters above.
The status of a specific transaction can be retrieved by using a GET call to /tool/Transaction for a specific transaction PKID. The PKID, also known as the transaction ID, or transaction_id is available in the synchronous response to an asynchronous mutator transaction.
For example, if the transaction_id in the response is [pkid], then the transaction can be polled with:
GET https://<server_address>/api/tool/Transaction/[pkid]
It is recommended to use asynchronous transaction call back mechanism described in “Asynchronous Mutator Transaction Status Callback”. If this can not be used, a consumer of the Cisco Unified Communications Domain Manager 10.x/11.5(x) API can also use this polling mechanism to poll the status of individual transactions using the poll action of the transaction tool. A user interface that allows a user to monitor the progress of a given transaction can use the following method to retrieve the status of a given transaction:
GET /api/tool/Transaction/[pkid]/poll/?format=json
The response contains essential status of the transaction, for example:
{ [pkid]: { status: "Success", href: "/api/tool/Transaction/[pkid]", description: "Name:RDP-auser1857 Description:RD for auser1857" } }
Transactions that have failed can, under certain circumstances, be replayed. This means that the transaction is re-submitted with the original request parameters. This is done by specifying the PKID of the transaction
GET https://<server_address>/api/tool/Transaction/[pkid]/replay/
The transaction current operation replays the transaction and the result returns the list view of the transaction log.
Transactions can be edited and then replayed under certain circumstances. This means that the transaction is re-submitted with the updated request parameters. This is done by specifying the PKID of the transaction:
GET https://<server_address>/api/tool/Transaction/[pkid]/edit-replay/
The transaction current operation edit and then replays the transaction and the result returns the list view of the transaction log.
The sub-transactions of a transaction with PKID can be retrieved by submitting the following URI
GET https://<server_address>/api/tool/Transaction/[pkid]/sub_transaction/
The log messages of a transaction with PKID can be retrieved by submitting the following URI
GET https://<server_address>/api/tool/Transaction/[pkid]/log/
Use the available URL endpoint and parameter to list the transaction actions as they may be shown in the transaction log.
GET api/tool/Transaction/choices/? field=action& hierarchy=[hierarchy]& format=json
[ { "value": "Auto Migrate Base Customer Dat", "title": "Auto Migrate Base Customer Dat" }, { "value": "Auto Migrate Base Provider", "title": "Auto Migrate Base Provider" }, { "value": "Auto Migrate Base Site Dat", "title": "Auto Migrate Base Site Dat" }, { "value": "Auto Migrate Dial Plan", "title": "Auto Migrate Dial Plan" }, { "value": "Auto Migrate Feature Subscriber Phone Cft", "title": "Auto Migrate Feature Subscriber Phone Cft" }, { "value": "Auto Migrate Hotdial Data", "title": "Auto Migrate Hotdial Data" }, { "value": "Auto Migrate Init Ippbx", "title": "Auto Migrate Init Ippbx" }, { "value": "Auto Migrate Internal Number Inventory", "title": "Auto Migrate Internal Number Inventory" }, ...
by the following values for the URL parameter filter_field:
Transaction ID: id
Start or end submitted time: submitted_time
The transaction message: message
by also listing sub transactions using the URL parameter and value subtransactions=true. By default, sub transactions are not listed, in other words, the value is false.
To carry out a filter on sub-transactions of a parent transaction, the /sub-transactions/ endpoint is added to the GET request:
/api/tool/Transaction/[parent-pkid]/sub-transactions/
To carry out a filter on transaction logs of a parent transaction, the /logs/ endpoint is added to the GET request:
/api/tool/Transaction/[parent-pkid]/log/
The transaction filters do not apply to logs.
eq (equals)
ne (not equals)
gt (greater than)
gte (greater than or equals)
lt (less than)
lte (less than or equals)
The date-time is a filter_text value for filter_field=submitted_time.
“T” is the time separator and the character should be added.
“Z” indicates UTC time and the character should be added.
“f” represents the decimal fraction of a second and the character should not be added. The specification of the decimal fraction is optional.
For example:
2016-06-29T14:41:00.01Z
GET api/tool/Transaction/? hierarchy=[hierarchy] &format=json &filter_field=submitted_time &filter_text=2016-06-29T14:41:00.01Z &filter_condition=gt
To filter between transaction IDs or times, two parameter sets are needed.
GET api/tool/Transaction/? hierarchy=[hierarchy] &format=json &filter_field=id &filter_text=12000 &filter_condition=gt &filter_field=id &filter_text=13000 &filter_condition=lt
GET api/tool/Transaction/? hierarchy=[hierarchy] &format=json &filter_field=submitted_time &filter_text=2016-06-29T14:41:00Z &filter_condition=gt &filter_field=submitted_time &filter_text=2016-06-29T15:41:00Z &filter_condition=lt
If the upper or lower bound in the filter are not available, the transactions with values between the filte values and the bound are returned.
a parent transaction has: parent: null
a sub transaction has: parent: <pkid>, where <pkid> is the value of the parent attribute pkid.
data: { username: "system", status: "Success", description: "", parent: null, pkid: "01a559c5-e77f-40e7-8403-683d7204d1e1", friendly_status: "Success", detail: "HcsLdapSyncSchedule--1", action: "Execute Schedule", href: "/api/tool/Transaction/01a559c5-e77f-40e7-8403-683d7204d1e1/", txn_seq_id: "17693", data_type_: "tool/Transaction", message: "", submitted_time: "2016-07-14T12:13:41.758000Z" }
data: { username: "system", status: "Success", description: "", parent: "f4daa234-590d-4002-a3b0-8c329c583d1d", pkid: "019f44a3-df6e-4e4f-86f3-a09a6b91e482", friendly_status: "Success", detail: "10.120.2.221", action: "Import Ldap", href: "/api/tool/Transaction/019f44a3-df6e-4e4f-86f3-a09a6b91e482/", txn_seq_id: "17695", data_type_: "tool/Transaction", message: "models completed.", submitted_time: "2016-07-14T12:13:43.075000Z" }
In the case of a transaction error, the message attribute value will show the corresponding error message. If a custom message was defined in a provisioning workflow, and the response is the result of the workflow, the value will be the custom message.
To filter transaction messages, the parameter filter_field=message is used, with at least one of the following additional filter criteria:
a date range of maximum 7 days using submitted_time
filter_condition=contains
filter_condition=startswith
ignore_case
Note | Note that a filter is by default case insensitive. If the case is explicitly set, then it must be added to each filter parameter group to ensure proper parameter grouping. |
The additional criteria do not apply to sub-transaction message filters, because the [parent-pkid] in the URL serves as an additional filter.
GET api/tool/Transaction/? hierarchy=[hierarchy] &format=json &filter_field=submitted_time &filter_text=2016-06-25T14:41:00Z &filter_condition=gt &ignore_case=false &filter_field=submitted_time &filter_text=2016-06-29T15:41:00Z &filter_condition=lt &ignore_case=false &filter_field=message &filter_text=Invalid%20business%20key &filter_condition=contains &ignore_case=false