Deletes one or more individual records from your knowledgebase data.

Syntax

 ew.EWDelete(String sessionId, String tableName, long[] keys,
    DeleteRule deleteRule, long[] replacementKeys);

Usage

Use EWDelete to delete one or more existing records from any given table. 

The operation accepts a list of identifiers for the records to be deleted in one transaction. The transaction will either succeed if each individual record has been successfully deleted or a rollback is performed otherwise. 

The EWDelete call is analogous to the DELETE statement in SQL.

Rules and Guidelines

When deleting records, consider the following rules and guidelines:

• The username that was used to obtain the specified session token must have sufficient access rights to delete individual records within the specified table.
• Agiloft allows one to establish relationships between the records in different tables and ensures the data integrity once the links are forged.

In the presence of such relationships when the delete operation is performed via GUI, the user who triggers the operation would be prompted via a series of dialogs to resolve the conflicts in each case. 

When the same operation is triggered programmatically it is necessary to specify the policy to be applied for conflict resolution beforehand via a deleteRule argument. 

This is achieved via a deleteRule parameter that can take one of the four values:

• • ERROR_IF_DEPENDANTS - fails when there are any dependents,
  • APPLY_DELETE_WHERE_POSSIBLE - tries to delete all dependent records, when delete cannot be done an attempt to unlink the record is made,
  • DELETE_WHERE_POSSIBLE_OTHERWISE_UNLINK - same as above,
  • APPLY_UNLINK - tries to unlink dependent records,
  • UNLINK_WHERE_POSSIBLE_OTHERWISE_DELETE - tries to unlink all dependant records, when unlink cannot be done an attempt to delete the record is made,
  • REPLACE_WITH_ANOTHER - tries to link dependent records to the substitute one specified in the replacementKeys.

Normally the decision which policy to use is taken at the "design" time and depends on the structure of the knowledgebase.

Notes

• If the specific strategy fails the error message returned will suggest alternatives to be used. One may use REST interface to find the best strategy.
• If APPLY_DELETE_WHERE_POSSIBLE or DELETE_WHERE_POSSIBLE_OTHERWISE_UNLINK strategies are used and the configuration of the knowledgebase allows it, a special "Fast Delete" algorithm is used, the same as via the GUI.
• Certain objects cannot be deleted via the API.

Basic Steps for Deleting Records

Deleting records involves the following basic steps:

1. Determine the id of each record that you want to delete. For example, you might call EWSelectFromTable to retrieve the identifiers for the set of records that you want to delete based on a specific criteria.
2. Construct the keys[] array and populate it with the identifiers of each record that you want to delete.
3. If the REPLACE_WITH_ANOTHER delete policy is used construct the substitute replacementKeys[] array.
4. Call EWDelete, passing in the table name, the keys[] array, the policy identifier and the substitute keys array, if necessary.
5. Process the results.

Example Task

In MyKB knowledgebase as user A delete case records #1234, #556, #123456 performing a "cascade" delete for all dependent records. 

The task is completed by performing the following steps:

1. Login to MyKB with "A" and "password", English as the locale language.
2. Construct the keys array.
3. Call EWDelete with for case table with these keys and APPLY_DELETE_WHERE_POSSIBLE as delete policy.
4. Logout.

Sample Code - Java

You can generate a sample Web Services code for any table by selecting Setup > Tables > [Edit Table] > API > Download Sample.

 public void delete() {
    long[] keys = new long[] { 1234L, 556L, 12346L };
    try {
    EWServiceAPI binding = new EWServiceAPIServiceLocator().getMyKB();
    String sessionId = binding.EWLogin("MyKB", "A", "password", "en");
    binding.EWDelete(sessionId, "case", keys,
    DeleteRule.APPLY_DELETE_WHERE_POSSIBLE, null);
    } catch ( EWWrongDataException e) {
    System.out.println(" EWWrongDataException encountered:\n\n" +
    e.getMessage());
    } catch ( EWOperationException e) {
    System.out.println(" EWOperationException encountered:\n\n" +
    e.getMessage());
    }
    }

Arguments

Response

The call does not return any value. A transaction is either completed as a whole or a rollback is performed.

Faults

EWSessionException - client not logged in or the session has expired; client should re-login. 

EWPermissionException - user used to create the session lacks sufficient privileges to perform a record deletion. 

EWWrongDataException - supplied data is wrong; caused by either the record to delete cannot be found – cause, array index, and key of the problematic record returned as parameters – or replacement failed – cause. array index, key of the problematic record and key of the replacement one as parameters.

EWOperationException - delete operation cannot be done – cause, array index and key of the problematic record returned as parameters; either the record has dependents – number of dependents as parameter; or the delete and the unlink are both not possible – relationship description as parameter; or the unlink is not possible – relationship description as parameter; or the replacement is not possible – relationship description as parameter; or the delete has failed – cause, array index, key of problematic record as parameters. 

EWIntegrityException - specified table cannot be found or its primary key cannot be identified. 

EWUnexpectedException - an unexpected exception has happened; user should report this for investigation.