Receipt Generation

Forms submissions will often require a simple human-readable ID (identification) 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 (Application Programming Interface).

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 four types: Text, Date, Random, and Sequential Numbers. You can choose to add any number of these to your Receipt ID. The exception is Sequential Numbers which you can only have 1 of in any Receipt ID. 

Important Note

• If you want to guarantee that the Receipt IDs being generated are unique to each submission you will need to include a Sequential Number component.

Instructions

1. Sign in to your site
2. Navigate to the Forms tab and select the applicable form or create a new form
   
3. Navigate to the Developer Tools tab
   
4. Scroll down to the Receipt Generation section and choose Receipt ID
   
5. Select the component to edit
   
6. Configure the Receipt Component type as needed
   • Text: Generates a piece of text that is displayed on every receipt. This can be used to add prefixes or separate the different sections of the Receipt ID by using a dash (-).
     
   • Date: Generates a specific chosen type of date in the Receipt. These can be used to create a specific date format for your users and allows you to know when the submission was completed by looking at the date section of the Receipt ID.
     
     • 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: Adds randomly generated text and or numbers to Receipts. Choose the number of characters and then what character sets to include. To avoid confusion for users we remove similar appearing characters in the generated Receipt ID (i, I, l, L, o, O, 0).
     
   • Sequential Number: Generates a sequential number for every submission. You can enter a starting number to begin the sequence at a higher number. Once the form is submitted a starting number cannot be added or modified.
     
7. Click Ok
   
8. Select Add New Component to add additional components, as needed
   
9. We recommend adding a dash between the components. You can do this by adding a Text component with a -
   
10. If needed, drag and drop the components into the desired order
    
11. View an example of what your receipt ID will look like
    
12. Scroll up and click Save
    
13. 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. Sign in to your site
2. Navigate to the Forms tab and select the applicable form or create a new form
   
3. Navigate to the Developer Tools tab
   
4. 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
     
5. 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 Message 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 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