Receipt Generation

Forms submissions will often require a simple human-readable ID to allow users to easily reference their form submissions. The Receipt Generation function allows you to create custom Receipt Ids for your form submission process.

 

There are two ways to create a Receipt ID, one is generating it using the built-in Receipt ID feature, and the second is using an API.

 

 

Create a Custom Receipt ID

By default, the receipt will be an 8-character random string created from numbers and uppercase letters. You are able to customize this Receipt Id by adding additional components. Components come in three types: Text, Date, and Random. You can choose to add any number of these to your Receipt Id.

 

Important Notes

• We do not guarantee that the receipt IDs generated in this manner are unique. However, depending on the configuration, the Receipt IDs can be made so that it is very unlikely that there will be submissions with the same Receipt Id. For example, the Receipt ID below has 84 trillion possible options generated each day.

 

 

Instructions

1. Navigate to the Forms tab and select the applicable form or create a new form
   
2. On the Summary tab, scroll down to the  Receipt Generation section and choose Receipt ID
   
3. Select the component to edit
   
4. Configure the Receipt Component type as needed
   • Text: Add the set piece of text that will appear in every Receipt ID
     
   • Date: Choose to use a portion of the date when the user opens the form
     
     
     • Day: The day of the month. For example, 01 or 25.
     • Month: The numerical month of the year. For example, 01 or 12.
     • Year (2 digit): The two-digit representation of the year. For example, 97 or 03.
     • Year (4 digit): The four-digit representation of the year. For example, 1997 or 2003.
   • Random: Select to use a randomly generated piece of text containing a specified number of letters and/or numbers
     
5. Click Ok
   
   
6. Select Add New Component to add additional components, as needed
   
7. We recommend adding a dash between the components. You can do this by adding a Text component with a -
   
   
8. If needed, drag and drop the components into the desired order
   
9. View an example of what your receipt ID will look like
   
10. Scroll up and click Save
    
    
11. Learn how to Display the Receipt ID to Users

 

Go to Article Navigation

 

Use a Custom URL / Hosted API

If you need to generate a receipt Id that cannot be catered for using the out-of-the-box Receipt Id functionality, then you will need to add a custom URL or a CivicOptimize-hosted API endpoint. This endpoint will be called on a form submission and allow you to generate an external Id. 

 

Examples

Below is an example of the request payload:

{ 
formsAppId: number
formId: number
externalIdUrlSearchParam: string | null
draftId: string | null
preFillFormDataId: string | null
jobId: string | null
previousFormSubmissionApprovalId: string | null
}

 

Below is an example of the response payload:

{ 
externalId?: string 
}

 

The External Id is required in the response payload if the externalIdUrlSearchParam is provided in the request payload.

 

 

Instructions

1. Navigate to the Forms tab and select the applicable form or create a new form
   
2. On the Summary tab, scroll down to the Receipt Generation section and choose Custom URL or Hosted API
   
   
   • Custom URL: Enter the URL address for an API endpoint
     
   • Hosted API: Select a Hosted API you have created in CivicOptimize and a Route from the drop-downs
     
3. Scroll up and click Save
   
   

 

Go to Article Navigation

 

Display the Receipt ID to Users

You can display the receipt ID using a custom submission message or by redirecting to a receipt page. 

 

Submission Message

In order to display the Receipt Id to your users you can add it in the successful submission message. Follow the instructions to Customize the Form Submission Display and include the {EXTERNAL_ID} in the message to allow users to see their Receipt ID once they complete the form. 

 

 

Create a Receipt Page

If you instead want to redirect the user to another form and display the Receipt Id there, you do so using the CivicOptimize pre-fill, and redirect URL functionality. Create your receipt page and add the URL of your Receipt page as a Redirect URL to your form.

 

 

Add the below text to the end of the redirect URL. Be sure to add the name of the element you want to pre-fill with the external Id. This will ensure that an element on your Receipt page is populated with the Receipt Id.

 

?preFillData={"name of your element":"{EXTERNAL_ID}"}

 

Go to Article Navigation