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

• Internal Query endpoint (alias internalQuery) in the Service Manager connection package.
• List of technicians by group report used in Service Manager.
   

Procedure
       

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

• Phase 1: Create and configure the form for collecting information

• Phase 2: Call the Internal Query endpoint to search for the group

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

• Phase 4: Check that the procedure works correctly

Prerequisites

1. Install and configure the Service Manager connection package.

      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.

• Display the new List of technicians by group report.
• Click  in the top banner and select REST API URL.
           
  The URL of the active page will be copied to the clipboard in the following format:

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

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.

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.

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.

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.

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.

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

• 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+"'"

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.
       

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

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.
           

2. Click Finish.

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

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

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.

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.

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.
           

3. Click Finish.

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

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

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.

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.

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

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

Click to see an example

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.

Phase 4: Check that the procedure works correctly

1. Run the procedure.

2. Enter the group name using the form.

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

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

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

List of files to download

• Report List of technicians by group

• PDF file for the use case

• Sample project