Self Help - Form Utils Connector - Use Case

Last modified on 2023/08/09 14:29

  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 attach a document to a Service Manager ticket by running a Self Help procedure. The document will then be available in the Attachments tab in Incident, Service Request, Change Request and Investment Request forms.

Objects used

Procedure
        Form util connector - Use case - Procedure.png

Overview

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

  • Prerequisites
    • Install and configure the Service Manager connection package
    • Create the Create a ticket procedure
    • Create the required input parameters for the Upload and attach a document to a ticket endpoint

Prerequisites

1. Install and configure the Service Manager connection package.

     Open url.png See the procedure

2. Create a new procedure in your Self Help project to enable users to create a ticket.

     Open url.png See the use case

     Package Service Manager - Use case - Create a ticket procedure.png

3. Create the required input parameters for the Upload and attach a document to a ticket endpoint.

  • Display the Properties view of the procedure and click Edit parameters.
            Form util connector - Use case - Prerequisites - Edit parameters.png
  • Specify the input parameters as shown below by clicking Add for each new parameter.
    • RFCNumber variable: Used to store the ticket number.
    • EncodedAttachment variable: Used to store the document encoded in base64.
    • AttachmentName variable: Used to store the name of the document to be attached to the ticket.

          Form util connector - Use case - Prerequisites - Add Input parameters.png

  • Click Finish.

4. Store the ticket number in the RFCNumber input variable.

  • Click the Success step.
  • Select the Macro tab in the Description pane of the step.
  • Enter the line below.
RFCNumber = CreateResult.ID;

          Form util connector - Use case - Prerequisites - Add Macro to store ticket number.png

5. Write a message for the Success step to proceed with the procedure.

  • Select the Content tab in the Description pane of the step.
  • Write a message enabling users to access the page for uploading a document.
            Form util connector - Use case - Prerequisites - Add Message to upload a document.png

Phase 1: Create and configure the form for collecting information

Step 1: Create the form

The form enables users to upload a document.

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

2. Add a simple input field.

  • attachment

          Form util connector - Use case - Form.png

3. Specify its properties.

  • Select the input type, File.
  • Click Finish.

          Form util connector - Use case - Form properties.png
 

Step 2: Add the form to a procedure step

1. Create a Page step after the Success step. Name it Upload attachment.

2. Click and drag the fAttachment form to the step.

          Form util connector - Use case - Form attached to step.png

Phase 2: Configure the Form utils connector

Phase 2.a: Convert form file to base64 method

Step 1: Create a new Connector resource

You create a Connector resource in order to encode the document to be attached to the ticket in base64. It uses the Form utils connector and the Convert a form file to base64 method.

1. Create a new Connector resource in the Resources folder of your Self Help project.

  • Select the connector, Form utils connector.
  • Click Next.
            Form util connector - Use case - Add Form util connector.png

2. Select the Convert form file to base64 method and click Next.

Note: Do not define the default parameters specific to the method. They will be defined when the connector is added to the procedure.

          Form util connector - Use case - Add Convert form file method.png

3. Click Next and click Finish.

The new Connector resource will be added to the Resources folder.
 

Step 2: Add the resource to a procedure step

1. Create an Action with Switch step after the Upload attachment step. Name it Form connector.

Two branches will be created.
        Form util connector - Use case - Form connector step.png

2. Click and drag the new Connector resource to the Form connector step and click Next.

 

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

3. Specify the input parameters of the method and click Next.

  • Form file identifier: Specify the fAttachment.attachment form field containing the file name entered by the user.

          Form util connector - Use case - Convert form file to base64 method - Input parameters.png

4. Specify the output parameters of the method.

  • Associate the EncodedAttachment input parameter with the result output variable.
  • Select the New variable checkbox next to the error output variable to create it. For the variable name, enter EncodedError. This variable will store the value of the output parameter.
  • Click Finish.
            Form util connector - Use case - Convert form file to base64 method - Output parameters.png

5. Click OK in the Parameters Refactoring window.

 The Convert form file to base64 method of the Form utils connector will be associated with the Form connector step. The document can now be encoded in base64.

Phase 2.b: Load form file and get its name method

Step 1: Create a new Connector resource

You create a Connector resource in order to retrieve the encoded document. It uses the Form utils connector and the Load form file and get its name method.

1. Create a new Connector resource in the Resources folder of your Self Help project.

  • Select the connector, Form utils connector.
  • Click Next.
            Form util connector - Use case - Add Form util connector.png

2. Select the Load form file and get its name method and click Next.

Note:  Do not define the default parameters specific to the method. They will be defined when the connector is added to the procedure.

          Form util connector - Use case - Add Load form file method.png

3. Click Next and click Finish.

The new Connector resource will be added to the Resources folder.
 

Step 2: Add the resource to a procedure step

1. Click and drag the new Connector resource to the Form connector step and click Next.

 

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

3. Specify the input parameters of the method and click Next.

  • Form file identifier: Specify the fAttachment.attachment form field containing the file name entered by the user.

          Form util connector - Use case - Load form file method - Input parameters.png

4. Specify the output parameters of the method.

  • Associate the AttachmentName input parameter with the result output variable.
  • Select the New variable checkbox next to the error output variable to create it. For the variable name, enter NameError. This variable will store the value of the output parameter.
  • Click Finish.
            Form util connector - Use case - Load form file method - Output parameters.png

5. Click OK in the Parameters Refactoring window.

The Load form file and get its name method of the Form utils connector will be associated with the Form connector step. The document can now be loaded and its name retrieved.

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

You must add a condition to the error output variables of the Convert form file to base64 method (variable EncodedError) and the Load form file and get its name method (variable NameError). If one of the variables is not null, this means that the call to the connector failed.
   Open url.png See the description of return codes

Step 1: Add a condition to check if the call to the connector failed

1. Define the condition that will show a failed process, indicated by a non-null value in one of the error output variables.

  • Double-click the <cond.> branch of the Form connector step.
            Form util connector - Use case - Add condition for Error.png

The window for defining the condition will appear.

  • Select the EncodedError output variable.
  • Select the is not null operator.
  • Click the + Add a condition line link to add a new row.
  • Select the NameError output variable.
  • Select the is not null operator.
  • Indicate that at least one of the conditions must be fulfilled by selecting At least one condition must be true (OR) from the list at the top of the window.
            Form util connector - Use case - Add condition Error.png

2. Click Finish.

The condition indicating a failed process will appear in the procedure.
        Form util connector - Use case - Condition for Error added.png

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

          Form util connector - Use case - 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 EncodedError and NameError output variables.

          Form util connector - Use case - Add condition - error.png
 

Step 2: Proceed with the procedure if the call to the connector was successful

If the call to the connector is successful, the procedure will proceed by calling the Upload and attach a document to a ticket endpoint in the Service Manager connection package.

     Open url.png See Phase 4: Call the Upload and attach a document to a ticket endpoint

Phase 4: Call the Upload and attach a document to a ticket endpoint

Step 1: Add the Upload and attach a document to a ticket endpoint in a procedure step

1. Create a Sub-procedure step after the Form connector step.

          Form util connector - Use case - Add 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 uploadDocuments alias of the Upload and attach a document to a ticket endpoint.

          Form util connector - 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 Upload and attach a document to a ticket endpoint

1. Specify the input parameters as shown below.

  • pInID: RFCNumber variable (number of the ticket for the attachment)
  • pInFileData: EncodedAttachment variable (encoded document)
  • pInFileName: AttachmentName variable (document name)

          Form util connector - 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: UploadResult variable
    • pOutStatus: UploadStatus variable 
    • pOutMessage: UploadMessage variable 

3. Click Finish.

The Upload and attach a document to a ticket endpoint will be associated via the sub-procedure.
        Form util connector - Use case - Step Sub procedure - Alias added.png

Phase 5: Define the conditions for testing the call to the Upload and attach a document to a ticket endpoint

You must add a condition to the UploadStatus output variable of the sub-procedure. If the variable is negative, this means that the call to the endpoint failed.
   Open url.png See the description of return codes

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

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

Two branches will be created.

          Form util connector - Use case - Step Sub procedure - Add condition.png

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

  • Double-click the <cond.> branch of the Test step.
    The window for defining the condition will appear.
  • Select the UploadStatus output variable.
  • Select the less than operator and enter the value 0.
            Form util connector - Use case - Step Sub procedure - Output parameters test.png

3. Click Finish.

The condition indicating a failed process will appear in the procedure.
        Form util connector - Use case - Step Sub procedure - Condition added.png

4. Create a Page step after the UploadStatus < 0 condition. Name it error.

          Form util connector - Use case - Step Sub procedure - Add condition for Error - To display message.png

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

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

          Form util connector - Use case - Step Sub procedure - Message - Error.png
 

Step 2: Process the results if the call to the endpoint was successful

1. Create a Page step after the default branch (i.e. the branch called if the conditions are not fulfilled). Name it Success.

          Form util connector - Use case - Step Sub procedure - Add condition for Success - To display message.png

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

3. Write a message informing users that the process was successful.

  • Display the ticket number using the RFCNumber output variable.
  • Display the name of the uploaded document using the AttachmentName output variable.

          Form util connector - Use case - Step Sub procedure - Message - Success.png

Phase 6: Check that the procedure works correctly

1. Run the procedure.

2. Create a ticket and upload an attachment.

          Form util connector - Use case - Test procedure - Entry informations.png

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

          Form util connector - Use case - Test procedure - Error process.png

4. Check that the document is correctly attached to the ticket if the process is successful.

          Form util connector - Use case - Test procedure - Success.png
        Form util connector - Use case - Test procedure - Success - Document attached to ticket.png

List of files to download

Tags:
Powered by XWiki © EasyVista 2022