Document Generator Function
Find out how to use the Document Generator pre-built function in OCI Functions to generate documents based on Office templates and JSON data.
Common Usage Scenarios
Common ways to use the Document Generator function include:
- Place an Office Template and JSON data in object storage and directly invoke the function to generate PDF documents and store the results in object storage.
Services related to the Document Generator function include:
Prerequisites And Recommendations
The following are best practices when using this pre-built function:
- The VCN linked to the application facilitates access to other OCI services by using a Service Gateway, Internet Gateway, or NAT gateway.
- Set the default memory size to 512 MB for most tasks. Using bigger data sets, bundling fonts, or using batch processing might require more memory.
- For batch processing, set the pre-built function timeout to 300 seconds.
Configuring the Document Generator Function
To configure a Document Generator function, perform the following steps:
The deploy dialog displays the tasks to deploy the function (see Finishing Pre-Built Function Deployment).
Configuration Options
Configuration Parameters
Name | Description | Required |
---|---|---|
PBF_LOG_LEVEL |
Logging level, options are DEBUG , INFO , WARN , and ERROR . Defaults to INFO . |
No |
Permissions
Running a function requires certain IAM policies. If you selected the Do not create a dynamic group and IAM policy option when creating the function, you must define the dynamic group and the IAM policy yourself.
To set the proper policies, perform the following steps:
- Create a dynamic group with the rule:
ALL {resource.id = '<function_ocid>' , resource.compartment.id = '<compartment_ocid>'}
- Configure an IAM policy using the dynamic group:
Allow dynamic-group <dynamic-group-name> to manage objects in compartment <compartment-name>
Replace
<function-ocid>
with the OCID of the function that you created in preceding steps. Replace
<dynamic-group-name>
with the name of the dynamic group that you created using the function's OCID.Replace
<compartment_ocid>
with the OCID of the compartment that contains the function.Invoking This Function
You can invoke the function in the following ways:
- Invoke the function directly as documented in Invoking Functions by creating a request body as shown in the following JSON example.
HTTP Request and Response Payloads
For a full list of request and response values, see Pre-Built Function Document Generator API.
Example Requests and Responses
Example 1: Generating a single PDF
Request:
{
"requestType": "SINGLE",
"tagSyntax": "DOCGEN_1_0",
"data": {
"source": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/movies.json"
},
"template": {
"source": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/movies.docx"
},
"output": {
"target": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/movies.pdf",
"contentType": "application/pdf"
}
}
Response - success:
{
"responseType": "SINGLE",
"code": 200,
"status": "OK",
"document": {
"type": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/movies.pdf",
"contentType": "application/pdf"
},
"metadata": {
"version": "1.0",
"configurationParameters": {
"FN_FN_NAME": "docgen",
"FN_APP_NAME": "docgen-app",
"FN_TYPE": "sync",
"FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
"OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
"FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
"FN_MEMORY": "512"
}
}
}
Response - failure:
{
"responseType": "ERROR",
"code": "400",
"status": "InvalidParameters",
"error": "No template has been specified.",
"metadata": {
"version": "1.0",
"configurationParameters": {
"FN_FN_NAME": "docgen",
"FN_APP_NAME": "docgen-app",
"FN_TYPE": "sync",
"FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
"OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
"FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
"FN_MEMORY": "512"
}
}
}
For more information, see:
Example 2: Generating multiple PDFs - data specified inline
Request:
{
"requestType": "BATCH",
"tagSyntax": "DOCGEN_1_0",
"data": {
"source": "INLINE",
"content": [{"name":"John"},{"name":"Monica"}]
},
"template": {
"source": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/Letters.docx",
"contentType": "application/vnd.openxmlformats-officedocument.wordprocessingml.document"
},
"output": {
"target": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/Letters{documentId}.pdf",
"contentType": "application/pdf",
"storageTier": "INFREQUENT_ACCESS"
}
}
Response - success:
{
"responseType": "BATCH",
"code": 207,
"status": "Multi-Status",
"documents": [
{
"documentId": 1,
"code": 200,
"status": "OK",
"document": {
"type": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/Letters1.pdf",
"contentType": "application/pdf",
"storageTier": "INFREQUENT_ACCESS"
}
},
{
"documentId": 2,
"code": 200,
"status": "OK",
"document": {
"type": "OBJECT_STORAGE",
"namespace": "my_namespace",
"bucketName": "my_bucket",
"objectName": "my_folder/Letters2.pdf",
"contentType": "application/pdf",
"storageTier": "INFREQUENT_ACCESS"
}
}
],
"metadata": {
"version": "1.0",
"configurationParameters": {
"FN_FN_NAME": "docgen",
"FN_APP_NAME": "docgen-app",
"FN_TYPE": "sync",
"FN_APP_ID": "ocid1.fnapp.oc1.phx.example...63m5hsmzzz",
"OCI_REGION_METADATA": "{\"realmDomainComponent\":\"oraclecloud.com\",\"realmKey\":\"oc1\",\"regionIdentifier\":\"us-phoenix-1\",\"regionKey\":\"PHX\"}",
"FN_FN_ID": "ocid1.fnfunc.oc1.phx.example...h523viuzzz",
"FN_MEMORY": "512"
}
}
}
For more information, see:
Document Names in Batch Output
With "responseType": "BATCH"
, multiple documents are produced. You can control the naming of these documents using the required{documentId}
in the document name.
output.objectName format | Description | Examples |
---|---|---|
invoice{documentId}.pdf |
No padding. Starts at 1. | invoice1.pdf, invoice2.pdf |
invoice{documentId|zeroPadding=auto}.pdf |
Automatic padding based on number of documents in batch. Starts at 1. | invoice01.pdf ... invoice10.pdf |
invoice{documentId|firstId=51}.pdf |
No zero padding. Starts at 51. | invoice51.pdf, invoice52.pdf |
invoice{documentId|firstId=51,zeroPadding=5}.pdf |
5 digits left padding with 0. Starts at 51. | invoice00051.pdf, invoice00052.pdf |
invoice{documentId|zeroPadding=5}.pdf |
5 digits left padding with 0. Starts at 1. | invoice00001.pdf, invoice00002.pdf |
Supported Document Types
From Template (contentType) | To Output (contentType) |
---|---|
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document ) |
PDF (application/pdf) |
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document ) |
Microsoft Word >= 2010 (application/vnd.openxmlformats-officedocument.wordprocessingml.document ) |
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) |
PDF (application/pdf) |
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) |
Microsoft Excel >= 2010 (application/application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ) |
Fonts
The following fonts are available when generating a PDF:
- Caladea
- Cookie
- Carlito
- DejaVu
- LiberationMono (Courier)
- LiberationSans (Arial)
- LiberationSerif (Times New Roman)
- NotoSans-Black
- NotoSans-BoldItalic
- NotoSans-ExtraLight
- NotoSans-Light
- NotoSans-MediumItalic
- NotoSans-SemiBoldItalic
- NotoSans-BlackItalic
- NotoSans-ExtraBold
- NotoSans-ExtraLightItalic
- NotoSans-LightItalic
- NotoSans-Regular
- NotoSans-Thin
- NotoSans-Bold
- NotoSans-ExtraBoldItalic
- NotoSans-Italic
- NotoSans-Medium
- NotoSans-SemiBold
- NotoSans-ThinItalic
- NotoSansJP-Bold
- NotoSansJP-Regular
- NotoSansKR-Regular
- NotoSansKR-Bold
- NotoSansSC-Regular
- NotoSansSC-Bold
- NotoSansTC-Regular
- NotoSansTC-Bold.otf
- NotoSansArabic-Regular
- NotoSansArabic-Bold
- NotoSansHebrew-Regular
- NotoSansHebrew-Bold
- NotoSerif-Bold
- NotoSerif-BoldItalic
- NotoSerif-Italic
- NotoSerif-Regular
- OracleSans-Bold
- OracleSans-Regular
- Oswald-Bold
- Oswald-ExtraLight
- Oswald-Light
- Oswald-Medium
- Oswald-Regular
- Oswald-SemiBold
If you need a font that is not in this list, you can specify a font bundle in the Document Generator request. A font bundle is a zip file containing .ttf and .otf files that will be used during PDF generation.
Document Generator Template Tags
For a full list of template tags, see Document Generator Template Tags
Troubleshooting
OCI Functions common status codes
The following table summarizes common OCI Functions errors that you might encounter when working with pre-built functions:
Error Code | Error Message | Action |
---|---|---|
200 | Success | None |
404 | NotAuthorizedOrNotFound | Verify that the required policies are configured (see Running Fn Project CLI commands returns a 404 error). |
444 | Timeout |
The connection between the client and OCI Functions was interrupted during function execution (see Invoking a function causes the client to report a timeout, and a 444 error is shown in the function's logs). A retry might solve the issue. Note that most clients have an inner timeout of 60 seconds. Even when the pre-built function timeout is set to 300 seconds, the following might be required:
For more information, see Invoking Functions. |
502 | (various) | Most issues return a 502 status code (see Invoking a function returns a Function failed message and a 502 error). A 502 error with the message "error receiving function response" might be resolved by increasing the memory allocation. A 502 might occur occasionally when the function is in some transient state. A retry might solve the issue. |
504 | Container failed to initialize | The application's shape must be compatible with the function (for example, GENERIC_X86). |
To further identify the cause, enable logging features for the pre-built function (see Storing and Viewing Function Logs). For detailed information on troubleshooting a function, see Troubleshooting OCI Functions.
Document Generator pre-built function status codes
Status Code | Description |
---|---|
200 | Success |
207 | For a responseType=BATCH, verify the response code for each individual document |
400 | Validation error or Processing error. If an ObjectNotFound error is returned, ensure that the subnet containing the function has access to the Object Storage service. |
500 | Internal error |
To further identify the cause, enable logging features for the pre-built function (see Storing and Viewing Function Logs).
Log Analysis Tips
All the pre-built functions provide an option to specify the logging level as a configuration parameter. You can set the logging level to DEBUG
to get more information.
Since an application has multiple functions, the pre-built function log entries are identified by the prefix "PBF | <PBF NAME> ".
For example, a log entry for the Document Generator pre-built function looks similar to the following:
"PBF | Document Generator | INFO | 2023-08-31T20:19:51.181593Z | 2. LOG001 - Setting Log Level to : DEBUG"