Change request creation from an attached file

This topic contains a basic description of creating requests from a file and associated configuration actions. The out-of-the-box FireFlow template used for creating change requests based on an attached file is the 120: Generic Request template, however users can create their own customized templates to create change requests from an attached file.

Change request from file process

Requestors can create new change requests based on the details included in a file attached to their change request. The process is as follows:

1. The requestor chooses a request template that supports the Generic Workflow and for which uploading an attachment is enabled. The template can be the FireFlow out-of-the-box Generic template (i.e., the 120: Generic Request template) or a custom Generic template created by the user. See Add and edit request templates.

2. If creating change requests from a file has been configured on the template, the user can attach one file specifying the required change details that will be used to create the change requests.

   Note: To view a sample worksheet filled with data that is expected by the out-of-the-box parsing script, see /usr/share/fireflow/local/extras/Firewall Rules Request Example.xls.

3. After the requestor submits the change request, FireFlow runs a parsing script that attempts to convert the attached file to XML format. During this process, FireFlow validates the input and produces an informative message for each problem found in the attached file. With this information the user can make all the corrections required in one edit session and submit a new change request with the corrected file.
   

   Note: Validation of the attachment's data before ticket creation is always done for single mode. It is done for multiple mode only if the ForceValidAttachmentsBeforeCreateTickets configuration parameter is enabled.
   If validation is not enforced, change requests will be created only from valid lines in the file.

4. When parsing is free of errors, FireFlow converts the XML file to one or more change requests.
   If the parsing script is configured for single change request creation, then all traffic lines in the file are interpreted as multiple traffic lines in a single change request. If the script is configured for multiple change request creation (the FireFlow default mode), each traffic line in the file is interpreted as a separate change request, and the change requests are linked to each other via their Depends On field.

   Note: By default, FireFlow uses an out-of-the-box parsing script, /usr/share/fireflow/local/bin/parse_excel_example.pl, which supports creating multiple change requests from a file, where all of the change request data is on a single worksheet. There is no indication in the template which mode is being used. Administrators inform users regarding the mode being used in their enterprise. See Configure Multiple or Single Change Requests.

   Note: Parsing scripts work for all of the following formats and can be customized for other formats as well:
   

   • xls (Microsoft Excel up to 2003)
   • xlsx (Microsoft Excel 2007 and up)
   • sxc (OpenOffice 1.0 Spreadsheet)
   • ods (OpenOffice Spreadsheet)
   • csv (Comma-separated text values)

   Note: Your administrator can customize change request creation from a file by:
   

   • Allowing the attached file to be of various types (formats).
   • Configuring whether multiple or single change requests are created from the attached file.
   • Configuring the workflow to accommodate your special requirements.
     

   AlgoSec Professional Services can advise you on workflow customizations.

Configure the Parsing Script

Do the following:

1. To enable the creation of change requests from an attached file that is in a format not supported by the default parsing script, obtain a custom parsing script from AlgoSec Professional Services.

2. Log in to the FireFlow server using the username "root" and the related password.

3. Do one of the following:

   • To work with the default parsing script, copy parse_excel_example.pl from /usr/share/fireflow/local/bin/ to /usr/share/fireflow/local/etc/site/bin/.
   • To work with a custom parsing script, save the custom script under /usr/share/fireflow/local/etc/site/bin.

4. Give the parsing script execute permissions, by running the following command:

   chmod a+x [script-name]

   Where script-name is the name of the parsing script.
   

5. Use the generic procedure to set the configuration parameters described below. For details, see Override FireFlow system defaults.

6. Configuration Parameter Name	Description	Value
   AttachmentParsingScripts	Setting this parameter is required to configure change request creation from a file.	The path of the parsing script. For example, "/usr/share/fireflow/local/etc/site/bin/custom_parsing_script1.pl" => ["xls", "xlsx", "sxc", "ods", "csv"] Separate multiple parsing script paths with commas
   AutoCreateTicketsFromAttachments	Enables/disables automatic creation of change requests from files.	1. To enable automatic creation of change requests from uploaded files. (Default) 0. To require manual triggering of change request creation from uploaded files.
   ForceValidAttachmentsBeforeCreateTickets	Enables/disables validity enforcement for uploaded files.	1. To enable validity enforcement for uploaded files. (Default) 0. To disable validity enforcement for uploaded files.

7. If required, follow the procedure in Configure Multiple or Single Change Requests

8. Restart FireFlow to enable the configuration changes.

Configure Multiple or Single Change Requests

The parsing script determines whether a single change request or multiple change requests are created from the attached file.


Do the following:

1. Under /usr/share/fireflow/local/etc/site/bin/, open the parsing script.

2. Locate the following lines:
   

# In this example: Multiple tickets modemy $mode = $MULTIPLE_TICKETS_MODE;# Set mode to $SINGLE_TICKETS_MODE if you wish to work in single ticket mode# my $mode = $SINGLE_TICKETS_MODE;

3. Uncomment the my $mode line that reflects the mode you want to use, and comment the my $mode line that reflects the mode you do not want to use.
   For example, to create a single change request from file, modify the lines as follows:

   # In this example: Multiple tickets mode# my $mode = $MULTIPLE_TICKETS_MODE;# Set mode to $SINGLE_TICKETS_MODE if you wish to work in single ticket modemy $mode = $SINGLE_TICKETS_MODE;

4. Save the script.

Disable change request creation from file

There are two methods of disabling request creation from file.
Method 1
Using the generic procedure for overriding system defaults, disable the configuration parameter AttachmentParsingScripts. For details, see Override FireFlow system defaults.

Method 2 - Recommended

This method provides more flexibility. You set request creation from file to yes or no for one template or several templates, without affecting all the request templates. This method also does not require restarting FireFlow.

1. Click on Request Templates in the FireFlow main menu (left side)

2. Select Request Type: Generic Change

3. Scroll down to Create Change Requests From File: and select the No radio button or the Yes radio button, as required.

4. Click Save Template or to save this to a specific Generic Change template, click Save As.

5. Click on New Request and open the saved template.

6. Scroll down to the Create Change Requests From File: label and verify that the text after it says yes or no in accordance with what you configured in step 3 above.