Transaction Filters

In addition to the filter parameters that can be applied to transactions as indicated in the topic on API Parameters, transactions in particular can be filtered:

• 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.

The parameters can have the filter_condition values:

• 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.

The format follows RFC3339: [https://tools.ietf.org/html/rfc3339] and is YYYY-MM-DDTHH:MM:SS.fZ, where:

• “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:

June 29 2016 14 hours 41 minutes 0.01 seconds UTC, is:

2016-06-29T14:41:00.01Z

To filter for transactions after this date-time, the API call is:

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.

For example:

• To filter transaction IDs between 12000 and 13000:

  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
  

• To filter transactions between June 29 2016 14 hours 41 minutes UTC and June 29 2016 15 hours 41 minutes UTC (no fraction of a second in the example):

  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 filter values and the bound are returned.

When the URL parameter subtransactions=true is used, the data object in the JSON API response shows:

• a parent transaction has: parent: null
• a sub transaction has: parent: <pkid>, where <pkid> is the value of the parent attribute pkid.

The example snippets below show the values of parent:

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

  • an additional filter_field, with one of the conditions:

    • filter_condition=contains
    • filter_condition=startswith

    Also required is the case sensitive parameter:

    • ignore_case

    Note that a filter is by default case insensitive. If the case is explicitly set, then it should be added to each filter parameter group in order 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.

  The example below is a message filter that contains “Invalid business key”, by date range:

  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