Making Blank Paperwork Repeat Dynamically – ServiceTrade

Using Adobe Acrobat Pro DC (or 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. You can use this method with blank paperwork rules to further automate how your forms populate.

This article will cover three specific ways to make your forms repeat dynamically based on the number of Assets, Subassets, or Services on a given Appointment.

Note: 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

Open the PDF you want to add the custom metadata in Using Adobe Acrobat Pro DC (or possibly other PDF editors.)
Click File.
Then click Properties to open the Document Properties Menu.
Click the Custom tab.

The image above shows the Custom tab open in the Document Properties Menu. To work correctly, you need to enter rules in both the Name and Value custom fields without any punctuation.
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.

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

Repeat Dynamically based on Asset Type and Number of Assets

To make a PDF repeat dynamically based on a selected number of Assets you will need two custom fields and they should be as follows:

The 1st custom field Name should be "repeatAsset" and its Value should be the desired Asset Type listed in ServiceTrade.
This field indicates you want the form to repeat dynamically on a selected Asset Type.
The 2nd custom field Name should be "repeatAssetDivisor" and its Value is the number of the selected Asset Type that you want the PDF to repeat on (the value whole number greater than zero.)

How repeatAsset and repeatAssetDivisor Works

The PDF will be repeated for each "chunk" of Asset Type you provided for the Value of "repeatAsset".

The "chunk's" size is determined by the number you provided for the Value of "repeatAssetDivisor".

On each repeated PDF, only that "chunk" of Assets will be populated into the fillable PDF fields, starting with the first Asset position:

"Servicetrade_job_assets-[INSERT ASSET TYPE]-1-[INSERT FIELD TYPE]"

Example:
If your Custom Properties are set as follows:

And your PDF only has backflow fillable fields.

The PDF will repeat for every 3 backflow Assets and the fields on the form will repeat sequentially.

So if the Job has 8 backflow Assets, the PDF will repeat 3 times (once for the first 3 backflow Assets, a second time for the second 3, and a third time for the remaining 2.)

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.

Example:
You have a one-page inspection document that needs to be repeated 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 the first Asset position.

always "Servicetrade_job_assets-hvac_unit-1-type"
never "Servicetrade_job_assets-hvac_unit-2-type", "Servicetrade_job_assets-hvac_unit-3-type", or any following position of the Asset's fillable field.

A typical use case for a repeatAssetDivisor value greater than 1 is when Assets are displayed in a tabular format.

You may have a long list of alarm system devices or fire extinguishers that need to be displayed on a PDF and you need the PDF to repeat for a set number of Assets.

In this case, the repeatAssetDivisor value should equal the number of rows available in the list.

You would use fillable fields for first Asset positions through the repeatAssetDivisor value in this case.

Example:
If you wanted to show 3 backflow Assets model numbers on each page, your repeatAssetDivisor would be 3 and you would use the fillable fields:

Servicetrade_job_assets-backflow-1-model
Servicetrade_job_assets-backflow-2-model
Servicetrade_job_assets-backflow-3-model

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)

Repeat Dynamically based on Subasset Type and Number of Subassets

To make a PDF repeat dynamically based on a selected number of parent Assets and also repeat dynamically based on a selected number of their Subassets (child Assets) you will need 4 custom fields and they should be as follows:

The 1st custom field Name should be "repeatAsset" and its Value should be the desired Parent Asset Type listed in ServiceTrade.
This field indicates you want the form to repeat dynamically on a selected Asset Type.
The 2nd custom field Name should be "repeatAssetDivisor" and its Value is the number of the selected Parent Asset Type that you want the PDF to repeat on (the value whole number greater than zero.)
The 3rd custom field Name should be "repeatSubasset" and its Value should be the desired Subasset Type listed in ServiceTrade.
The 4th custom field Name should be "repeatSubassetDivisor" and its Value is the number of the selected Subasset Type that you want the PDF to repeat on (the value whole number greater than zero.)

How repeatSubasset and repeatSubassetDivisor Works

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 first Subasset position as follows:

"Servicetrade_job_assets-[INSERT PARENT ASSET TYPE]-1-subasset-[INSERT SUBASSET TYPE]-1-[INSERT SUBASSET FIELD]"

Use Cases for repeatSubassetDivisor

A typical use case for repeatSubasset and repeatSubassetDivisor is when you need to repeat a form for a system inspection multiple times.

Example:
You have an alarm system inspection form, but "inside" each of those inspection forms you need to repeat a list of 10 alarm device 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 value of 1.

Then you would also want a repeatSubasset value of "alarm_device", and a repeatSubassetDivisor value equal to the number of alarm device rows on the PDF (in this case 10.)

Each form's parent Asset data will be in the first Alarm System position, and the Subassets' data will be available in first Subasset positions through the repeatSubassetDivisor value like so:

"Servicetrade_job_assets-alarm_system-1-subasset-alarm_device-1-[INSERT SUBASSET FIELD TYPE]"

Important Notes

If a parent Asset has multiple different types of Subassets, then only the desired "chunk" of Subassets for the repeatSubasset Asset type is included on each instance of the PDF, but all the other Subasset types are included on each page.
- Example: 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)

Repeat Dynamically based on Services

To make a PDF repeat dynamically based on Services you will need 1 custom field and it should be as follows:

The 1st custom field Name should be "repeatService" and its Value should be either "0" or "1".

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 the form will populate only that instance's Service into the Service fields.

You would use fields like: "Servicetrade_job_services-1-service_description", or "Servicetrade_job_services-1-service_line", etc.)
Meaning that you should only use the first Service position on these forms.
You would never use "Servicetrade_job_services-2-service_line", "Servicetrade_job_services-3-service_description", etc.

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 the first Asset position. on these forms.

You would always use fields like "Servicetrade_job_assets-backflow-1-type".
You would never use fields like "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", then 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.

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 (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.
If you have additional questions about us providing support to add these fillable fields and metadata to your existing PDF forms, please reach out to our Customer Support or your Account Manager to discuss using Professional Services.