Using Adobe Acrobat Pro DC (and possibly other PDF editors), it is possible to add custom metadata directly into the PDF document itself that drives the number of copies of forms that will show up on a given job. Use this method in conjunction with blank paperwork rules to automate forms further.
This article will cover two specific ways to do this, resulting in extra copies of paperwork generating automatically, based on the number of services or assets on a given appointment.
Custom Field Metadata Rules
IMPORTANT: You can make paperwork repeat based on the services or assets, but not both. Likewise, users can design a single document to repeat multiple assets per page or repeat multiple pages per asset.
Accessing Custom Fields
To make the necessary edits using Adobe Acrobat Pro DC:
1. Open the PDF you want to add the custom metadata in, then go to File > Properties
2. Then, go to the "Custom" tab in the "Properties" window.
3. The image above shows the "Custom" tab open in the PDF Properties modal window. To work correctly, you need to enter rules in both the Name and Value custom fields without any punctuation (specifically, do not include the colons, commas, or double quotes that eventually appear in the JSON metadata. Metadata rules will function correctly if you enter your custom field values without punctuation. If you add any punctuation, it will appear redundantly in the JSON metadata and will not work correctly).
The section below details the various available rules within the Custom fields above.
Custom Field Metadata Rules
IMPORTANT: Be sure to provide one of the expected values for each metadata field that you wish to use. You will receive unexpected results if, for instance, you give an asset name instead of a number for repeatAssetDivisor, or a number instead of an asset name for repeatAsset.
repeatService
To make a PDF repeat dynamically based on services, the custom field name should be 'repeatService' and the custom field value should be '1' or '0'.
'repeatService' Value is 1
- If the value is 1, then the PDF will be repeated for each active service on the job that matches the blank paperwork rule's service line and service description. On each PDF instance, the form will populate only that instance's service into the service fields
- Example: ('servicetrade_job_services-1-service_description', servicetrade_job_services-1-service_line', etc.).
- Meaning that you should only use service position #1 on these forms; you would never use 'servicetrade_job_services-2-service_line', 'servicetrade_job_services-3-service_description', etc.
- For example, if a blank paperwork rule is assigned to the 'Backflow' service line and has a service description of 'inspection,' then the PDF will be repeated for each service on the job with a service line of 'Backflow' and a service description containing the word 'inspection.'
- On each instance of the PDF, the asset data filled into the fillable fields is only the data for the specific asset associated with the service on that instance. You should only use asset position #1 on these forms (always 'servicetrade_job_assets-backflow-1-type'.
- You would never use for example: 'servicetrade_job_assets-backflow-2-type').
- If the service is not associated with an asset, the asset fields on that PDF instance will be empty.
'repeatService' Value is 0
- If this value is 0, the PDF will render once, regardless of how many services are on the job.
- You will need to use additional positions if you need to accommodate multiple services.
- Example: 'servicetrade_job_services-2-service_line', 'servicetrade_job_services-3-service_description', etc
- The default value if not entered is 0.
repeatAsset and repeatAssetDivisor
To make a PDF repeat dynamically based on assets:
- The custom field name should be 'repeatAsset', and the expected value is one of the asset types listed in ServiceTrade.
- The custom field name should be 'repeatAssetDivisor, then the expected value is a whole number greater than zero.
Expected behavior
The PDF will be repeated for each "chunk" of assets if this value is provided. The chunk size is determined by repeatAssetDivisor. On each PDF instance, only that chunk's assets will be populated into the fillable PDF fields, starting with position #1 like so,
'servicetrade_job_assets-[INSERT ASSET TYPE]-1-model'.
For example, if using an alarm device asset type you would write
'servicetrade_job_assets-alarm_device-1-model'
If repeatAssetDivisor is 10, the PDF will repeat for every 10 alarm device assets. So if the job has 27 alarm device assets, the PDF will repeat 3 times (once for the first 10 alarm devices, a second time for the second 10, and a third time for the remaining 7).
Use Cases for repeatAssetDivisor
A typical use case for a repeatAssetDivisor of 1 is when each asset should get its own copy of the PDF – for instance, if there is a one-page inspection document that needs to be completed for each asset being inspected. This is common for large assets such as HVAC units, fire suppression systems, etc. You would only ever use fillable fields for asset position #1 in this case
Here is an example of this using the HVAC unit asset type.
(always ‘servicetrade_job_assets-hvac_unit-1-type’, never servicetrade_job_assets-hvac_unit-2-type’, ‘servicetrade_job_assets-hvac_unit-3-type’, etc.)
A typical use case for a sizeable repeatAssetDivisor value is when assets are displayed in a tabular format – for instance, when a list of alarm system devices or fire extinguishers is to be displayed. In this case, the repeatAssetDivisor value should equal the number of rows available in the list. You would use fillable fields for asset positions #1 through the repeatAssetDivisor value in this case.
So for example, if you wanted to show 10 alarm devices on each page, your repeatAssetDivisor would be 10 and you would use 'servicetrade_job_assets-alarm_device-1-name' through 'servicetrade_job_assets-alarm_device-9-name'.
If repeatAsset is not provided, the PDF will only be rendered once, regardless of how many assets are on the job; the repeatAssetDivisor value will be ignored. If repeatAsset is provided but repeatAssetDivisor is not provided, then the PDF will be repeated once per asset (repeatAssetDivisor is assumed to be zero).
repeatAsset default: empty (do not repeat on assets)
repeatAssetDivisor default: 1 (repeat PDF for each asset)
repeatSubsset and repeatSubssetDivisor
repeatSubasset expected values: one of the asset types listed in ServiceTrade.
repeatSubassetDivisor expected values: a whole number greater than zero
If a value is provided, then the PDF will be repeated for each "chunk" of active subassets beneath a parent asset. The chunk size is determined by repeatSubassetDivisor. On each instance of the PDF, only that chunk's subassets will be populated into the fillable PDF fields, starting with position #1 like so,
'servicetrade_job_assets-[INSERT ASSET TYPE]-1-subasset-[INSERT SUBASSET TYPE]-1-name'
A typical use case for repeatSubasset / repeatSubassetDivisor is when you need to repeat a form for a system inspection multiple times (for instance, an alarm system inspection form), but "inside" each of those inspection forms you need to repeat a list of subassets (for instance, the alarm system devices that belong to each alarm system).
In this example, you would use a repeatAsset value of 'alarm_system', a repeatAssetDivisor of 1, a repeatSubasset value of 'alarm_device', and a repeatSubassetDivisor value equal to the number of alarm device rows on the form. Each form's parent asset data will be in position #1, and the subassets' data will be available in subasset positions #1 through the repeatSubassetDivisor value like so,
'servicetrade_job_assets-alarm_system-1-subasset-alarm_device-1-name'.
If a parent asset has multiple different types of subassets, then only the desired "chunk" of subassets for the repeatSubasset asset type are included on each instance of the PDF, but all the other subasset types are included on each page. For instance, if repeatAsset is 'generator', repeatSubasset is 'generator_starter', and repeatSubassetDivisor is 10, but a given generator asset has both generator_starter and generator_controller subassets, then each PDF will include only 10 generator_starter assets (at positions #1 through #10), but it will include the entire list of generator_controller subassets (at positions #1 through the total number of generator_controller subassets).
It is not possible to repeat subassets for a combined list of multiple subasset types. You must pick a single subasset type by which to repeat.
These values are only used if repeatAsset is provided, and if repeatAssetDivisor is 1. If repeatAsset is not provided, both repeatSubasset and repeatSubassetDivisor are ignored. If both repeatSubasset and repeatSubassetDivisor are provided, but repeatAssetDivisor is something other than 1, then the actual repeatAssetDivisor value is ignored, and 1 is used instead.
repeatSubasset default: empty (do not repeat on subassets)
repeatSubassetDivisor default: 1 (repeat PDF for each subasset)
Additional notes
- If repeatService and repeatAsset are both provided, repeatService is used and repeatAsset is ignored. You cannot repeat PDFs based on both service and asset.
- Subassets are always included "underneath" their parent asset (for example, 'servicetrade_job_assets-alarm_system-1-subasset-alarm_device-1-name', even in cases where the asset data on a PDF is limited to a single asset or a single service.
- If onlyJobAssets is 0 (that is, all location assets should be included), then you can reach subassets either directly (something like 'servicetrade_job_assets-alarm_device-1-name') or indirectly (something like 'servicetrade_job_assets-alarm_system-1-subasset-alarm_device-1-name').
- If onlyJobAssets is 1 (that is, include only the job's assets), you can still reach the subassets underneath each of the job's assets, even though they are not directly associated with jobs on the service, via something like 'servicetrade_job_assets-alarm_system-1-subasset-alarm_device-1-name'. You cannot directly reach subassets through something like 'servicetrade_job_assets-alarm_device-1-name' in this case.