Service Manager Connection Package - Use Case - Internal Query Endpoint

Last modified on 2023/08/09 14:21

  To help you set up this use case, you can download the relevant documentation and sample project. Open url.png See List of files to download

This use case enables you to display a list of the members belonging to a Service Manager group by running a Self Help procedure.

Objects used

Procedure
       Internal query - Use case - Procedure.png

Caution

The group name searched for is case-sensitive.

Overview

The implementation of the use case is performed in several phases:

  • Prerequisites
    • Install and configure the Service Manager connection package
    • Import the List of technicians by group report to Service Manager
    • Retrieve the report URL

Prerequisites

1. Install and configure the Service Manager connection package.

     Open url.png See the procedure

2. Import the List of technicians by group report to Service Manager.

  • Download the file below to your workstation.

  Report List of technicians by group

  • Import the downloaded file to Service Manager by selecting Administration > Import / Export > Import in the menu.

3. Retrieve the URL of the Service Manager report required for configuring the Internal Query endpoint in phase 2.

Note: Your profile must be authorized to display the REST API URL menu.

  • Display the new List of technicians by group report.
  • Click Tools icon.png in the top banner and select REST API URL.
             Copy REST API URL of report.png
    The URL of the active page will be copied to the clipboard in the following format:
https:~/~/{your_server}}/api/v1/{your_account}/internalqueries?queryguid={query guid id}&filterguid={filter guid id}&viewguid={view guid id}
  • Paste the content of the clipboard in your text editor in order to store it temporarily. It will be required when specifying the Internal Query endpoint in phase 2.

Phase 1: Create and configure the form for collecting information

Step 1: Create the form

The form enables users to enter the name of the group whose members they want to display.

1. Create a new form in the Resources folder of your Self Help project. Name it Data.

2. Add a simple input field called Group.

          Internal query - Use case - Form.png
 

Step 2: Add the form to a procedure step

1. Create a new procedure in your Self Help project. Name it Search for employees from group.

2. Create the first step, i.e. a Page step. Name it Input data.

          Internal query - Use case - Step Input information.png

3. Select the Content tab in the Description pane of the step.

4. Write a message asking users to enter the group name.

5. Click and drag the Data form to the end of the message.

          Internal query - Use case - Step Input information - Content tab.png

Phase 2: Call the Internal Query endpoint

Step 1: Add the Internal Query endpoint to a procedure step

1. Create a Sub-procedure step after the Input data step.

          Internal query - Use case - Step Sub procedure.png

2. Double-click the step.

The properties window of the procedure will appear.

3. Select the Link with an alias option and select the internalQuery alias of the Internal Query endpoint.

          Internal query - Use case - Step Sub procedure - Add alias.png

4. Click Next.

The window for configuring input and output parameters for the endpoint will appear.
 

Step 2: Configure the Internal Query endpoint

1. Specify the input parameters as shown below.

Caution: Remember to add double quote marks around each parameter value (" ").

  • pInQueryGuid: Copy and paste the ID of the query found in the report URL, surrounded by double quotes. This is the one you stored earlier in your text editor during the Prerequisites stage. It corresponds to the {query guid id} instruction.

https://{your_server}}/api/v1/{your_account}/internalqueries?queryguid={query guid id}&filterguid={filter guid id}&viewguid={view guid id}

  • pInFilterGuid: Copy and paste the ID of the filter found in the report URL, surrounded by double quotes. It corresponds to the {filter guid id} instruction.
  • pInViewGuid: Copy and paste the ID of the view found in the report URL, surrounded by double quotes. It corresponds to the {view guid id} instruction.
  • pInSearch: Enter the instruction as follows, "AM_GROUP.GROUP_EN='"+Data.group+"'"

Best Practice icon.png  To search for a group whose name is in another language, replace EN with the code of the relevant language.

example  Search in French ==> AM_GROUP.GROUP_FR

          Internal query - Use case - Step Sub procedure - Add alias - Input Output parameters.png

2. Specify the output parameters of the endpoint.

  • Select the New variable checkboxes next to the output variables to create them.
  • Enter a meaningful name for the variables where the output parameter values will be stored so that users can identify them easily.
    • pOutResult ==> Enter the groupResult variable
    • pOutStatus ==> Enter the groupStatus variable
    • pOutMessage ==> Enter the groupMessage variable
    • pOutSelList ==> Enter the groupSelList variable

3. Click Finish.

The Internal Query endpoint will be associated via the sub-procedure.
       Internal query - Use case - Step Sub procedure - Alias added.png

Phase 3: Define the conditions for testing the call to the endpoint

You must add a condition to the groupStatus output variable of the sub-procedure. If the variable is not null, this means that the process failed. If the variable is null, this means that the process was successful. You must then add a condition to the groupResult output variable to check the number of records retrieved by the search.
    Open url.png See the description of return codes

Step 1: Add a test step

1. Create an Action with Switch step after the sub-procedure.

2. Name it Test.

Two branches will be created.

          Internal query - Use case - Add condition.png
 

Step 2: Add a condition to check if the call to the endpoint failed

1. Define the condition that will show a failed process, indicated by a negative value for the groupStatus output variable.

  • Double-click the <cond.> branch.
    The window for defining the condition will appear.
  • Select the groupStatus output variable.
  • Select the less than operator and enter the value 0.
             Internal query - Use case - Add condition for Error.png

2. Click Finish.

The condition indicating a failed process will appear in the procedure.

          Internal query - Use case - Condition for Error added.png

3. Create a Page step after the <cond.> branch. Name it error.

          Internal query - Use case - Add condition for Error - To display message.png

4. Select the Content tab in the Description pane of the step.

5. Write a message informing users that the process failed and display the error stored in the groupMessage output variable.

          Internal query - Use case - Message - Error.png
 

Step 3: Add a condition to check if the call to the endpoint was successful with no results returned

The groupResult output variable contains a JSON object. If the search does not return any results, the number of values in the object will be equal to zero and the groupResult.recordcount output variable will be equal to zero.

1. Create another conditional branch after the Test step.

  • Right-click the Test step.
  • Select Insert a Step > Add a Branch from the contextual menu.

          Internal query - Use case - Add branch condition for Success without record.png

2. Define the condition that will show that no record was found, indicated by a null value in the groupResult.recordcount output variable.

  • Double-click the new <cond.> branch.
    The window for defining the condition will appear.
  • Select the groupResult.recordcount output variable.
  • Select the equals operator and enter the value 0.
             Internal query - Use case - Add branch condition for Success without record - Add condition.png

3. Click Finish.

The condition indicating that no result was found will appear in the procedure.

          Internal query - Use case - Branch condition for Success without record added.png

4. Create a Page step after the new <cond.> branch. Name it No result.

          Internal query - Use case - Add branch condition for Success without record - Add condition without record.png

5. Select the Content tab in the Description pane of the step.

6. Write a message informing users that the search did not return any results.

  • The Data.group variable indicates the name of the group selected by users in the Data form.

          Internal query - Use case - Message - Success without record message.png
 

Step 4: Process the results if the call to the endpoint was successful and the search returned results

The groupResult.recordcount output variable contains the number of records retrieved by the search.

1. Create a Page step after the default branch of the Test step. Name it Success.

          Internal query - Use case - Add condition - Success with records.png

2. Create a variable to present the list of group members in a table.

Note: The raw search results from the groupResult output variable are returned in a JSON object whose format is not readable as such.

  • Select the Macro tab in the Description pane of the step.
  • Define the macro for formatting the groupResult output variable.

  • Raw results: JSON format

    Excel result in JSON format.png

  • Results displayed in a table using a macro to format the groupResult output variable

    Excel result with macro format.png

3. Select the Content tab in the Description pane of the step.

4. Write a message informing users that the search returned one or more results.

  • Display the search results from the groupResult output variable.
    • The groupResult.recordcount variable indicates the number of records found.
    • The Data.group variable indicates the name of the group selected by users in the Data form.
    • The Listing variable displays the list of group members in a table once the JSON object is formatted.

          Internal query - Use case - Message - Success with records.png

Phase 4: Check that the procedure works correctly

1. Run the procedure.

2. Enter the group name using the form.

          Internal query - Use case - Test procedure - Entry informations.png

3. Check that the relevant message appears if the process fails.

          Internal query - Use case - Test procedure - Error process.png

4. Check that the relevant message appears if the group does not exist.

          Internal query - Use case - Test procedure - Success without record.png

5. Check the accuracy of the list of group members if the group exists.

Note: The value 1 displayed at the end of a row containing a name means that the group searched for is the employee's default group.

          Internal query - Use case - Test procedure - Success with record.png

List of files to download

Tags:
Powered by XWiki © EasyVista 2022