Document Generator Function

Find out how to use the Document Generator pre-built function in OCI Functions to generate PDF 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:

Object Storage

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:

On the Pre-Built Functions page, click Document Generator, and then click Create function.
Configure the Name, Compartment, and Application as follows:
- Name: A name of your choice for the new function. The name must start with a letter or underscore, followed by letters, numbers, hyphens, or underscores. Length can be 1–255 characters. Avoid entering confidential information.
  To create the function in a different compartment, click Change Compartment.
- Application: Select the application in which you want to create the function.
  If a suitable application doesn't already exist in the current compartment, click Create new application and specify the following details:
  - Name: A name for the new application. Avoid entering confidential information.
  - VCN: The VCN (virtual cloud network) in which to run functions in the application. Optionally, click Change Compartment to select a VCN from a different compartment.
  - Subnets: The subnet (or subnets, up to a maximum of three) in which to run functions. Optionally, click Change Compartment to select a subnet from a different compartment.
  - Shape: Select GENERIC_X86. The Document Generator function is only supported on x86-based architectures.
  - Tagging options: If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
Configure the IAM policy for pre-built functions.

By default, OCI Functions creates a dynamic group and an IAM policy with the policy statements required to run the pre-built function. Make no changes to accept the default behavior.

If you don't want OCI Functions to automatically create the dynamic group and policy, select Do not create a dynamic group and IAM policy.

Important

If you select the Do not create a dynamic group and IAM policy option, you must define the dynamic group and the IAM policy yourself. For more information, see Permissions.
Configure function memory and timeout values as follows:
- Memory: The maximum amount of memory that the function can use while running, in megabytes. This is the memory available to the function image. (Default: 512 MB)
- Timeout: The maximum amount of time that the function can run for, in seconds. If the function doesn’t complete in the specified time, the system cancels the function. (Default: 300)
(Optional) Configure Provisioned concurrency to minimize any initial delays when invoking the function by specifying a minimum number of concurrent function invocations for which you want to have execution infrastructure constantly available. (Default: Not selected)

If selected, specify the number of provisioned concurrency units assigned to this function. Default: 10.

For more information about provisioned concurrency, see Reducing Initial Latency Using Provisioned Concurrency.
Set the function configuration parameters as described in Configuration Options.
Optionally enter any tags in the Tagging options section. If you have permissions to create a resource, then you also have permissions to apply free-form tags to that resource. To apply a defined tag, you must have permissions to use the tag namespace. For more information about tagging, see Resource Tags. If you're not sure whether to apply tags, skip this option or ask an administrator. You can apply tags later.
Click Create.

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>

Note

Replace <function-ocid> with the OCID of the function that you created in preceding steps.

Note

Replace <dynamic-group-name> with the name of the dynamic group that you created using the function's OCID.

Note

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`)

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.
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"

Oracle Cloud Infrastructure Documentation