Page tree
Skip to end of metadata
Go to start of metadata

Test the SOAP Interface

This topic will enable you to establish the connection to the SOAP interface via the WSDL, and test several of the available requests. Ideally these tests should be performed on a 'clean' knowledgebase, prior to setting up complicating factors such as WS-SecurityThe instructions in this topic will use SOAPUI as a reference point, but if you would prefer to use another software tool with which you are more acquainted, just adapt the instructions to your own software environment.

Prerequisites

  • You must have the admin login details for your knowledgebase
  • The knowledgebase must have an Enterprise license. See Licensing for more information. 
  • Download and install SoapUI from here: https://www.soapui.org/downloads/soapui.html. The Open Source edition will work for this testing. 

Enable Web Services in the KB

  1. In the knowledgebase, go to Setup > System > Manage Web Services
  2. Ensure that the WS-Security enabled checkbox is not selected and that version 2 of SOAP is selected, then click Enable WS.
  3. The Enable WS button will be replaced by two new buttons, and the SOAP Web Services will show as being on.
  4. Click the link to the WSDL, which will open in a new tab in the URL format http://<SERVER>/ewws/<KBNAME>/EWServiceAPIv2?wsdl.
  5. Ensure that only the admin group has access to the SOAP and REST services. 

Add the WSDL to SOAPUI

  1. In SOAPUI, Click the SOAP icon to create a new SOAP project.
  2. Enter a name for the project, and in the Initial WSDL field paste the URL to the  Agiloft WSDL. 
  3. Ensure that Create sample requests for all operations? is selected, and click OK. This will create the project, with all of the available SOAP calls listed. 
  4. Expand the first level to see the full project menu, right click DemoSoapBinding, and select Show Interface Viewer. 
  5. Open the Service Endpoints tab of the interface viewer, and check the details of the WSDL URL. It should be formed as above. Select the endpoint and click Assign.
  6. In the Assign Endpoints dialog, select All Requests from the drop-down list, and click OK. 
  7. Exit the interface viewer. 

Test the SOAP Calls

At this point, you can test the calls from SOAP to the knowledgebase. To test a call from the list...

  1. Expand it to see the request
  2. Double click the request. 
  3. Replace the existing parameters - which are written in the format <ParameterName>?</ParameterName> - with the relevant values from the knowledgebase
  4. Click the green arrow to run the request. 

Follow the example test cases below to test some of the available requests. Many of the examples below will use the Support Cases table (WSCase) to test the requests. 

EWLogin

  1. Add the following values to the EWLogin request:

    <dem:EWLogin>
                  <String_1>KBNAME</String_1>
                  <String_2>admin</String_2>
                  <String_3>admin_password</String_3>
                  <String_4>en</String_4>
    </dem:EWLogin>
  2. Click Run. This will return something like the following response, which includes a session string between the <result> tags:

    <env:Envelope xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
       <env:Header/>
       <env:Body>
          <demo:EWLoginResponse xmlns:demo="http://Demo.api.ws.enterprisewizard.com">
             <result>78658161687694</result>
          </demo:EWLoginResponse>
       </env:Body>
    </env:Envelope>
  3. Change the password in string_3 to an incorrect value and click Run.
    1. An error message similar to the following will appear: <message>[http-0.0.0.0-80-1][1618616486d] login/password combination admin/****** for knowledgebase KB1</message>
  4. Set the username and password to an existing, non-admin user and click Run. 
    1. An error message similar to the following will appear: 

      <ns1:EWPermissionException xmlns:ns1="http://api.ws.enterprisewizard.com" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <message>not allowed, please check logs</message>
      </ns1:EWPermissionException>
  5. Enter the correct admin username and password again and click Run. 
    1. Write down the session string, which will be used in later tests. 

EWRead

  1. Add the following values to the EWRead_WSCase request and click Run:

    <dem:EWRead_WSCase>
                       <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                       <recordID>0</recordID>
    </dem:EWRead_WSCase>
    1. An error message similar to the following will appear: <message>[http-0.0.0.0-80-6][1503916816216] no data found for 0</message>
  2. Replace the recordID with an existing Support Case record in the KB.
    1. The response will be an XML string with the details of the Support Case record. 

EWSelectFromTable

  1. In the Support Cases table, create a new record and assign it to the system user 'Ralph Knowles'; or if the user does not exist, assign them to another user and replace String_3 below with their name. 

    1. Add the following values to the EWSelectFromTable request and click Run:

      <dem:EWSelectFromTable>
                         <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                         <String_2>case</String_2>
                         <String_3>assigned_person='Ralph Knowles'</String_3>
      </dem:EWSelectFromTable>
    2. The response will return the ID of the Support Case, as well as any other Support Case records assigned to that user.
  2. Modify the string_3 parameter with a SQL query, which will return the record with the highest ID from the table. Note that the [DB_TABLE_NAME] can be found in the Table Name field of the General tab of the Table wizard. Click Run.
    1. The response will return the ID of the highest record number for the Support Case table. 

EWSelectAndRead

  1. Add the following values to the EWSelectAndRead_WSCase request and click Run:

     <dem:EWSelectAndRead_WSCase>
                  <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                  <where>assigned_person='Ralph Knowles'</where>
    </dem:EWSelectAndRead_WSCase>
    1. The response will return the details of any records assigned to user Ralph Knowles. 
  2. Modify the <where> condition so that it will find only one record; for example: <where>assigned_person='Ralph Knowles' and wfstate=1</where>, and click Run.
    1. The response will contain the full data of that record.

EWCreate

  1. Open the EWCreate_WScase request. 

  2. Remove all of the field tags apart from problem_Description and summary, and add the parameter values in this way, then click Run:

     <dem:EWCreate_WSCase>
                  <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                  <WSCase>
                                 <problem_Description>Test ticket for SOAP</problem_Description>
                                 <summary>SOAP test create</summary>
                  </WSCase>
    </dem:EWCreate_WSCase>
  3. This request will create a very basic new record in the Support Cases table. The response will give the record ID in this way: <result>361</result>.
  4. In the KB, locate the new record to verify that it was created successfully. 

EWCreateAndRead

  1. Open the EWCreateAndRead_WSCase request. 
  2. Remove all of the field tags inside <WSCase> apart from problem_Description and summary, and add the parameter values in this way, then click Run:

     <dem:EWCreateAndRead_WSCase>
    <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                  <WSCase>
                                 <problem_Description>Test ticket 2 for SOAP</problem_Description>
                                 <summary>SOAP test create and read</summary>
                  </WSCase>
    </dem:EWCreateAndRead_WSCase>
  3. This request will create a basic new record in the Support Cases table. The response will give the full data for the new record.
  4. In the KB, locate the new record to verify that it was created successfully. 

EWUpdate

  1. Open the EWUpdate_WSCase request.
  2. Remove all of the field tags apart from ID and Priority and add the parameter values in this way, then click Run:

    <dem:EWUpdate_WSCase>
                       <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                       <WSCase>
                                      <id>RECORD_ID_FOR_UPDATE</id>
                                      <priority>OPTION_CRITICAL</priority>
                       </WSCase>
    </dem:EWUpdate_WSCase>
  3. This request will change the priority of the Support Case record to Critical. The response will give the full data for the updated record. 
  4. In the KB, locate the record and check that its priority was changed. 

EWDelete

  1. Add the following values to the EWDelete request and click Run:

     <dem:EWDelete>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                  <String_2>case</String_2>
                  <arrayOflong_3>
                                 <value>RECORD_ID_FOR_DELETE</value>
                  </arrayOflong_3>
                  <DeleteRule_4>APPLY_DELETE_WHERE_POSSIBLE</DeleteRule_4>
                  <arrayOflong_5>
                  </arrayOflong_5>
    </dem:EWDelete>
  2. This request will delete the record number in the KB. The response will show no record data. 
  3. In the KB, search for the record and confirm that it was deleted. 
  4. Execute the same request with the identical settings and check that the response is similar to the following: <message>[http-0.0.0.0-80-5][1504006477104] Operation cannot be done. Not all records can be removed.</message>

EWGetChoiceLineID

  1. Add the following values to the EWGetChoiceLineID request and click Run: 

     <dem:EWGetChoiceLineId>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                  <String_2>case</String_2>
                  <String_3>priority</String_3>
                  <String_4>Critical</String_4>
    </dem:EWGetChoiceLineId>
  2. This request will return the line number in the Priority choice list for the value Critical. The response will be a value like <result>6</result>.
  3. Change the <String_4> value to a non-existent priority and click Run.
    1. The response will be similar to the following message: <message>[http-0.0.0.0-80-4][1504007797277] No choice line found for value Defcon 6</message>
  4. Change the <String_3> value to some non-choice field like 'summary' and click Run.
    1. The response will be similar to the following:  <message>[http-0.0.0.0-80-4][1504007877613] unexpected exception: null</message>.

EWAttachFromSOAPAttachment

  1. Create a txt file with the file name testfile, and save it to a location on your system. 

  2. Add the following values to the EWAttachFromSOAPAttachment request, replacing the <key> value with an existing Support Case record number:

    <dem:EWAttachFromSOAPAttachment>
                  <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                  <tableName>case</tableName>
                  <key>419</key>
                  <fieldName>downloadable_files</fieldName>
                  <fileName>testfile.txt</fileName>
    </dem:EWAttachFromSOAPAttachment>
  3. Click Attachments below the request window, then click + and select the filename.txt file from your system. 
  4. Click Run.  The request will attach the file to the record in the Support Case table. The response will be similar to <result>1</result>.
  5. In the KB, open the record and check that the file has been attached to the Downloadable Files field. 
  6. Create a new file and execute the same request again with it. Check that the result has been incremented to <result>2</result>.
    1. In the KB, open the record and check that the new file was added to the Downloadable Files field.

EWRetrieveAttachedAsSOAPAttachment

  1. Add the following values to the EWRetrieveAttachedAsSOAPAttachment request, replacing the <key> value with the Support Case record number from the example above, then click Run: 

     <dem:EWRetrieveAttachedAsSOAPAttachment>
                  <sessionId>SESSIONID_FROM_LOGIN_RESPONSE</sessionId>
                  <tableName>case</tableName>
                  <key>419</key>
                  <fieldName>downloadable_files</fieldName>
                  <filePosition>1</filePosition>
    </dem:EWRetrieveAttachedAsSOAPAttachment>
  2. The request will retrieve the attached file from the Downloadable Files field with a file position of 1. The response will not show any data, but below the response window the Attachments button will indicate that there is 1 attachment. 
  3. In the request, change the <filePosition> vaue to an incorrect attachment number like 80, then click Run.
    1. The response will be similar to the following: <message>[http-0.0.0.0-80-7][1504013330298] Blob field id in table case does not contain 81 files, but less (2) for key 419</message>

EWRemoveAttached

  1. Add the following values to the EWRemoveAttached request, replacing the <long> value with the Support Case record number from the example above, then click Run:

    <dem:EWRemoveAttached>
                       <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                       <String_2>case</String_2>
                       <long_3>419</long_3>
                       <String_4>downloadable_files</String_4>
                       <int_5>1</int_5>
    </dem:EWRemoveAttached>
  2. The request will remove the first attached file from the Downloadable Files field. The response will be similar to <result>1</result>, with the number in the <result> tag being the number of remaining attached files. 
  3. In the KB, open the record and check that the first file was removed from the Downloadable Files field. 

EWSearchTable

  1. Add the following values to the EWSearchTable request, then click Run:

     <dem:EWSearchTable>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                  <String_2>case</String_2>
                  <arrayOfString_3>
                                 <value>id</value>
                                 <value>summary</value>
                  </arrayOfString_3>
                  <String_4>Open Cases</String_4>
    </dem:EWSearchTable>
  2. The request will search the Support Cases table for all records with a status of Open. The response will show the field values for each of the open cases. 
  3. Change the search name in String_4 to a non-existent search and click Run. The response will be similar to <message>No search=Open Cas for table=WSCase</message>.

EWSearchTablePaginated

  1. Add the following values to the EWSearchTablePaginated request, then click Run:

     <dem:EWSearchTablePaginated>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                  <String_2>case</String_2>
                  <arrayOfString_3>
                                 <value>id</value>
                                 <value>summary</value>
                  </arrayOfString_3>
                  <String_4>Open Cases</String_4>
                  <int_5>0</int_5>
                  <int_6>1</int_6>
    </dem:EWSearchTablePaginated>
  2. The request will search the Support Cases table for the first page number (int_6) of the first record (int_5). The response will show the fields on page 0 of the first record in the table. 
  3. Modify the <int_6> value to 2 (record count), then click Run.
    1. The response will show the fields from the first two records. 
  4. Modify the <int_5> value to 1 (page number), then click Run.
    1. The response will show the first two records on page 1 of the table. 
  5. Modify the <int_value> to 777, then click Run.
    1. The response will show no records.
  6. Modify <int_5> to 0, and <int_6> to 1000, then click Run.
    1. The response will show all records in the table. 

EWSearchTableWithQuery

  1. Add the following values to the EWSearchTableWithQuery request, then click Run: 

    <dem:EWSearchTableWithQuery>
                       <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                       <String_2>case</String_2>
                       <arrayOfString_3>
                                      <value>id</value>
                                      <value>summary</value>
                                      <value>priority</value>
                       </arrayOfString_3>
                       <String_4>Open Cases</String_4>
                       <String_5>priority='Low'</String_5>
    </dem:EWSearchTableWithQuery>
    
  2. The request will search the Support Cases table for all open cases with a priority of Low. The response will show the fields for all records in Open status with a Priority of Low, including the ID Summary and Priority fields. 
  3. Change the condition for <String_5> to something like <String_5>priority='Low'&amp;&amp; summary~='How'</String_5>, then click Run.
    1. The response should return no errors and there should be a record data where the Summary field contains the word 'How'. 
  4. Change the search in <String_4> to a non-existent value, then click Run.
    1. The response will be something like <message>No search=Cases for table=WSCase</message>

EWSearchTableWithQueryPaginated

  1. Add the following values to the EWSearchTableWIthQueryPaginated request, then click Run:

     <dem:EWSearchTableWithQueryPaginated>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
                  <String_2>case</String_2>
                  <arrayOfString_3>
                                 <value>id</value>
                                 <value>summary</value>
                  </arrayOfString_3>
                  <String_4>Open Cases</String_4>
                  <String_5>priority='Low'</String_5>
                  <int_6>0</int_6>
                  <int_7>1</int_7>
    </dem:EWSearchTableWithQueryPaginated>
  2. The request will search the Support Cases for open cases with a priority of Low, in the first record (int_7) on the first page (int_6) in the table. The response will show all fields from that record. 
  3. Modify the <int_7> value to 2, to find the first two records, then click Run.
    1. The response will show all the fields in the first two records on the first page of the table that match the search query. 
  4. Modify the <int_6> value to 777 to find the first two records on the 777'th page of the table, then click Run.
    1. The response will show no records.
  5. Set the <int_6> value to 0, and <int_7> to 1000, then click Run.
    1. The response will show the fields for all records in the table. 

EWLogout

  1. Add the following values to the EWLogout request, then click Run:

     <dem:EWLogout>
                  <String_1>SESSIONID_FROM_LOGIN_RESPONSE</String_1>
    </dem:EWLogout>
  2. The request will log out the session. The response will not have any errors.
  3. Execute any of the previous requests with the same values. The response will be similar to  <message>[http-0.0.0.0-80-7][1504083695004] not logged in or this session has timed out</message>

Deactivate Web Services

  1. As the admin user, log into the testing knowledgebase, then go to Setup > System > Manage Web Services
  2. Click Disable WS.
  3. The message will change to "SOAP Web Services are currently Off".
  4. Try to perform the test case for EWLogin.
  5. The response will be similar to HTTP Status 404 - /ewws/Demo/EWServiceAPIv2.

Testing SOAP Security

The following examples will enable you to test the security of your SOAP application. Leave your instance of SOAPUI configured as above. 

Add WS-Security to Web Services

  1. In the KB, go to Setup > System > Manage Web Services. Check that the wording states "SOAP Web Services are currently Off". 
  2. Check that 'version 2', and the WS-Security enabled checkbox, are both selected. 
  3. Write down the current TTL value - 10 by default. 
  4. Click Enable WS. 
  5. Select the 'admin' group for SOAP groups, even if it already shows the group as being selected. 
  6. Click Finish, then reopen the Web Services screen. 
  7. Check the wording states "SOAP Web Services are currently On". 

Login Without Security

  1. In SOAPUI, try to perform the test case forEWLogin
  2. The response will say something like <faultstring>This service requires &lt;wsse:Security>, which is missing.</faultstring>.

Configure SOAPUI for WS_Security

  1. In SOAPUI, double click the project root to open the settings wizard.
  2. Open the WS_Security Configurations tab to the Outgoing WS-Security Configurations tab. 
  3. Click + then add a name in the dialog, and save it. 
  4. In the bottom pane, click + then in the ADD WS Entry dialog, select Timestamp. Click OK.
  5. Click OK.
  6. In the Time To Live field that appears, enter the TTL value in the  Agiloft Web Services wizard. 
  7. Exit from the settings wizard. 

Login with Security

  1. In SOAPUI, select the EWLogin request, right click in the window and select Outgoing WSS > Apply <WS Config Name>
  2. Click Run.
  3. The response will return new timestamp data similar to the following:

     <wsse:Security ...>
                  <wsu:Timestamp wsu:Id="timestamp">
                  <wsu:Created>2016-10-12T13:54:35.482Z</wsu:Created>
                  <wsu:Expires>2016-10-12T13:54:45.482Z</wsu:Expires>
    </wsu:Timestamp>
    </wsse:Security>

EWSearchTable with Security

  1. Reopen the EWSearchTable request and add the Session ID from the previous example, then click Run.
  2. The response will be similar to <faultstring>This service requires &lt;wsse:Security>, which is missing.</faultstring>.
  3. Right click in the window and select Outgoing WSS > Apply <WS Config Name>, then click Run.
  4. The response will return the record data, with an additional <wsse:Security> section with timestamps. 

  • No labels