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

• Create a ticket procedure.  See the use case
• Form utils connector: Convert form file to base64 and Load form file and get its name methods.
• Upload and attach a document to a ticket endpoint (alias uploadDocuments) in the Service Manager connection package.
   

Procedure
        

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

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

• Phase 2: Configure the Form utils connector
  • Method for encoding a ticket attachment in base64
  • Method for retrieving the encoded document

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

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

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

• Phase 6: Check that the procedure works correctly

Prerequisites

1. Install and configure the Service Manager connection package.

      See the procedure

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

      See the use case

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.
          

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

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

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.
          

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

3. Specify its properties.

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

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.

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.
          

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.

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.
        

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.

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.
          

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.
          

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.

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.

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.
          

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

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.
          

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 EncodedError and NameError output variables.

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.

      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.

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.

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)

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.
        

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

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.
          

3. Click Finish.

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

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

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.

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.

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.

Phase 6: Check that the procedure works correctly

1. Run the procedure.

2. Create a ticket and upload an attachment.

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

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

List of files to download

• PDF file for the use case

• Sample project