Give us feedback
docmosis-connector
Service icon

Docmosis Connector

Stable version 1.0.0 (Compatible with OutSystems 11)
Published on 28 Feb by 
5.0
 (1 rating)
docmosis-connector

Docmosis Connector

Documentation
1.0.0

Processing Locations

Docmosis offers of choice of regions in which to process documents. Select from Asia/Pacific, EU and US to ensure low-latency and geo-bound processing.

In the Docmosis Connector for OutSystems, the processing location may be set via the BaseURL Site Property. Available URLs for each region may be found in your Docmosis Cloud Console, and include the following:

US - Oregon 
https://us.dws3.docmosis.com/api/
EU - Frankfurt 
https://eu.dws3.docmosis.com/api/
AU - Sydney 
https://au.dws3.docmosis.com/api/

If the value of the BaseURL Site Property is left unspecified, the connector will default to AU: https://au.dws3.docmosis.com/api/.


Security and Reliability

Below is a summary of Docmosis’ Cloud Security Measures:

  • Load balanced, high-performance, redundant, geographically distributed and monitored 24/7.
  • Over 99.99% uptime consistently for over 7 years.
  • All communication with the Docmosis Cloud is SSL encrypted and templates and other uploaded content are stored encrypted at rest.


Actions

Each action has an AccessKey input parameter, which sets the Docmosis API access key to be used for that request. The Docmosis_IS module also has an AccessKey Site Property, which may be defined via the Service Centre.  An action will always use the input parameter if it has a value; otherwise, the connector will fall back to the value of the AccessKey Site Property.

To get your Docmosis Access Key, follow these steps to sign up for a Free Trial account:

  • Confirm your email address, as per the given instructions.
  • Set your password and activate your account.
  • Navigate to the ‘Account’ page:
  • Click ‘Show Access Key’, then copy the string revealed below.


ListTemplates

Returns a list of the templates currently stored on the Docmosis server.

Input Parameters

  • AccessKey - Your access key. 
  • IncludeDetail - Include extra detail about templates in the Templates output parameter. Extra parameters are marked by a ‘*’.
  • Folder - Limit processing to the given folder. The returned names are always relative to the folder. 
  • IncludeSubFolders - Include the contents of sub folders (i.e. work recursively). 
  • Paging - Whether or not to return results in pages.
  • PageSize - Specify the size of pages. Defaults to 1000 but can be reduced.
  • PageToken - When paging is true, this token identifies the next page to retrieve. The page token is null for the first page. When the first page response returns, it contains the token required to request the next page. 

Output Parameters

  • Templates - The list of templates, having attributes for each template: 
    • Name. The template file name 
    • LastModified 
    • SizeBytes
    • TemplatePlainTextFieldPrefix. The placeholder prefix used when it was uploaded* 
    • TemplatePlainTextFieldSuffix. The placeholder suffix used when it was uploaded* 
    • TemplateDevMode. The dev mode setting used when it was uploaded* 
    • TemplateHasErrors. True if the uploaded template has errors* 
    • TemplateDescription. The description uploaded with the template * 
    • MD5. The MD5 hash code for the template. *
  • NextPageToken. The token required to request the next page. May be supplied to the PageToken input parameter on the next request.
  • TemplateListStale. If Docmosis detects changes to the template list are in progress (such as updates or deletions) this flag will be set to True to indicate the list is not necessarily up to date. This is only ever expected to be True for a short period after deletes or updates.


ListFolders

Returns a list of the folders on the Docmosis server in which templates are stored.

Input Parameters

  • AccessKey - Your access key. 

Output Parameters

  • Folders - A Text List of folder paths.


GetTemplates

Retrieves a template from the Docmosis server,  retaining all placeholders, and without merging any data.

Input Parameters

  • AccessKey. Your access key. 
  • TemplateNames. The full paths and filenames for the requested templates. Multiple templates will be returned as a ZIP archive, whereas a single requested template will be returned as single file of the format in which it was created.

Output Parameters

  • FileContent. A BinaryData object containing the requested template file.
  • FileName. The name and extension of the requested template file.


UploadTemplate

Uploads a template to the Docmosis server. If a template with the same filename and path already exists, the pre-existing template will be overwritten. This may be used in conjunction with the DownloadTemplate service action to facilitate editing of templates by end-users.

Input Parameters

  • AccessKey. Your access key. 
  • TemplateFile. The template file you are uploading. 
  • TemplatePath. The path at which the template should be stored. May include the filename, or this component may be specified in the TemplateName input parameter. If the path does not exist, it will be created.
  • TemplateName. An optional, overriding name. This may not include a path.
  • TemplateDescription. A description for the template. 
  • DevMode. If set to True, the upload is run in developer mode, meaning that if errors are detected in the template, the upload still succeeds. This allows later render requests to optionally display the errors in the template in a rendered document (using the render service’s own DevMode flag). In a production setting, a DevMode of true for upload is perfectly valid since the DevMode of the render service has the final say as to whether a document is produced. Defaults to True. 
  • KeepPrevOnFail. If set to True, the previous template of the same name will be left in place if the uploaded template has errors. If not specified (or False) the original template is always removed, even if this uploaded template has errors. This only has effect when DevMode is disabled (since DevMode is intended to allow templates with errors to be displayed by Docmosis). This parameter means that in production mode (non-developer mode) template uploads will not replace a working template with a bad template. Defaults to False. 
  • FieldDelimPrefix. If using plain text mark-up in your templates, this specifies the prefix delimiter identifying a field. The default is ‘<<’. 
  • FieldDelimSuffix. This is the closing delimiter for plain text fields. The default is ‘>>’. 
  • NormalizeTemplateName. If set to True the template name given will be NFC normalized (Unicode NFC normalization). The default is False.

Output Parameters (none)


DeleteTemplates

Deletes a template from the Docmosis server.

Input Parameters

  • AccessKey. Your access key. 
  • TemplateName. The full path and filename of the template. This parameter can be specified multiple times to delete multiple files.

Output Parameters (none)


RenderDocument

Outputs a document, comprising a specified template in which placeholder fields have been replaced with data specified in a JSON string. For example, the placeholder “Dear <<firstName>>,” in a chosen document would be replaced value of the JSON attribute { “firstName": “Neo” }  to yield “Dear Neo” after processing by RenderDocument.

For a demonstration of usage, see in the Docmosis Connector Sample, the block Docmosis_Sample/MainFlow/Render_Execute.

Input Parameters

  • AccessKey. Your access key. 
  • TemplateNames. A Text List containing the full paths and filenames of the templates to use. The template must have been uploaded previously with the template upload request or via the Cloud Console. Where multiple template names are given, a single OutputName for PDF output results in a single combined PDF. In all other cases, a ZIP file will be returned containing each rendered document. 
  • OutputNames. A Text List containing the names to give the rendered documents. If no format is specified (see OutputFormat), the format of the resulting document is derived from the extension of this name. For example, "resume1.pdf" implies a PDF format document. A name may be supplied without an extension (eg "resume1") and the OutputFormat parameter will specify the format(s) to return. If multiple template names are specified, multiple (matching) output names can be specified to create a ZIP of named outputs. 
  • OutputFormats. The format(s) of the rendered document. This can be a single format, as the [0] element in the list. Multiple formats imply a ZIP archive and OutputName will have ‘.zip’ appended as required. Files inside the ZIP archive will be named using OutputName and will have the format-specific extension appended as required. Valid options are given in the FileTypes static entity, and consist of the following: 
    • PDF, Doc, ODT, RTF, HTML, Plain Text, Docx, Zip
  • StoreTo. A StorageDestination List where each StorageDestination specifies where to send the resulting document. Each element has the following attributes: 
    • StorageType. A static entity with records Stream, MailTo, and  S3. Stream causes the file(s) to returned as BinaryData in the FileContent output parameter. MailTo cause the file(s) to be sent via email. S3 causes the file(s) to be sent to an S3 bucket. (Note, S3 functionality must be enabled in your Docmosis account.)
    • Filetypes. A list of FileType static entities to be sent to this destination.
    • Location. For MailTo, use this field for the mailing address. For S3, use this field for the bucket address and filename, e.g. my.amazon.bucket,mydocument1.pdf. Leave blank for Stream.
      If no specification is given, "stream" is assumed and the result will be streamed back to the requester.
  • CompressSingleFormat. Optionally choose to zip the result when a single output document is produced. The ZIP archive will contain a document in the specified format with a name based on OutputName + OutputFormat. The resulting zip file name will be the OutputName with the .zip extension appended as required. This option is ignored if more than one OutputFormat is specified. 
  • DevMode. The render service can be used in development or production modes respectively. If set to True, this operation will work in "dev" mode, meaning that if something is incorrect in the template, data or instructions, Docmosis will do its best to produce a document. Such a document may contain errors such as missing images and data, and wherever possible, Docmosis will highlight problems to indicate the failure. In production mode, errors in document rendering will result in a failure result only, and no document will be produced. The production mode is to ensure that a bad document is never produced/delivered to a recipient. The default mode is production (that is, DevMode is False).
  • Data. The data that will populate the document. This will be in JSON format. The type of data given determines the format of the response.
  • MailProperties. A structure containing parameters that apply when a MailTo StorageDestination has been appended to StoreTo
    • mailSubject If sending email, this will be used as the subject line of the email. 
    • mailBodyHtml If sending email, this will be used as the body of the email and will be sent as html format. 
    • mailBodyText If sending email, this will be used as the body of the email and will be sent as text. 
    • mailNoZipAttachments If this is set to True, any email attachments will be attached as individual files rather than as a single zip (when multiple formats are being used).
  • RequestId. Any string you would like to use to identify this job. This string will be returned in responses. 
  • SourceId. Any ID you would like to associate with this render. This could be a device id, a project code or any meaningful piece of data you associate with this render. This value can be reported later with associated monthly counts. Limited to 150 characters. 
  • StylesInText. If set to True, your data will be parsed looking for html-like mark-up. The following mark-up is supported:
    - Bold e.g. "this is <b>bold</b>"
    - Italics e.g. "this is <i>italics</i>"
    - Underline e.g. "this is <u>underline</u>"
    - Cell Colouring e.g. "<bgcolor="#ff0000"/>"
    The bgcolor mark-up must be at the beginning of your data and the template field must be inside a table-cell to take effect. 
  • PDFProperties. A structure containing parameters that apply when a PDF document is being produced.
    • ArchiveMode. Create pdf documents in PDF-A mode for long term storage. Note this setting disables certain PDF features such as password protection and external hyperlinks. 
    • Watermark. PDF documents will have the specified text added as a watermark across the document. 
    • Tagged. If enabled, the PDF documents will have extra information inserted to assist with low-vision readability tools. The alt-text for images in particular becomes “readable”.
    • RestrictPassword. Set the password for further security restrictions. 
    • RestrictPrinting. Restrict printing of the created PDF. Requires that RestrictPassword has been set. Valid options are given in the RestrictPrinting static entity, and consist of the following:
      • NoRestriction. Default.
      • NoPrint. Cannot be printed 
      • LowRes. Print only low resolution 
      • FullQuality. Print in full quality
    • RestrictEditing. Restrict editing of the created PDF. Requires that RestrictPassword has been set. Valid options are given in the RestrictEditing static entity, and and consist of the following:
      • NoRestriction. Default.
      • NoEditing. No edits allowed 
      • InsertAndRotate. Pages can be inserted and rotated 
      • FillForms. Form fields can be filled in 
      • FillFormsAddComments. Form fields can be filled and comments can be added 
      • AllButPageExtraction. Above 1-3 enabled, but page extraction disabled
    • RestrictCopy. Set whether copy of PDF content is disabled. Set to True, copying from the document is disabled. Requires that RestrictPassword has been set.
    • RestrictAllowAccessibility. Set whether content can be extracted by accessibility applications. True disables the accessibility access. Requires that RestrictPassword has been set and also RestrictCopy must be set. 
  • PasswordProtect. If specified, this parameter will set the password for PDF and DOC files created by the render. The password is used when opening the document. Use with care as setting the password means the recipient must know the password to read the document. Note: 
    • PDFArchiveMode will disable any password setting for PDF documents. 
    • Not supported in DOCX export.
  • IgnoreUnknownParams. If true, unknown parameters in the request are allowed and ignored. By default, the render service will return an error if a parameter is specified that is not expected (defined by this table).
  • Tags. A Text List of tags to record against this render. The tags can be later queried (using the “/api/getRenderTags” endpoint, not exposed in this connector) to retrieve stats such as page-counts and document-counts related to the tags.

Output Parameters

  • FileContent. A BinaryData object containing the rendered document. Null if StoreTo does not contain a Stream element.
  • FileName. The filename, including extension, of the rendered document. Null if StoreTo does not contain a Stream element.
  • RequestId_Response. The RequestId parameter as returned by the Docmosis API.


DeleteFiles

This service action deletes files stored in the Docmosis file storage area associated with your account.

Input Parameters

  • AccessKey. Your access key. 
  • Path. The name of the file or folder. 
  • IncludeSubFolders. If True all files within the given path are deleted also. Default is false.

Output Parameters (none)


GetSampleData

The GetSampleData service action allows sample data to be generated for a template based on the current structures in the template. The sample data can be created in JSON or XML format which can then be fed back to the render service to generate populated documents. 

The service creates values like “value1”, “value2” for each field element. 

If the template has an error in it, Docmosis will generate a blank data set.

Input Parameters:

  • AccessKey. Your access key. 
  • TemplateName. The name of the template for which to create sample data. 
  • Format. The format in which to return the sample data. Valid options are given in the SampleDataFormat static entity, and consist of JSON and XML.

Output Parameters:

  • SampleData. A Text attribute contain the JSON or XML data. This can be passed to the Data attribute of the RenderDocument  service action to render a document consisting of the generated sample data.


AccountSummary

Input Parameters:

  • AccessKey. Your access key. 

Output Parameters:

  • ShortMsg. A short message about the ready-status of the account.
  • AccountReady. Whether the account is ready to create documents.
  • PlanName. The name of the plan.
  • IsActivated. Is the account activated?
  • IsDisabled. Has the account been disabled?
  • PagesUsed. Pages rendered this month
  • MonthlyQuota. Monthly page quota
  • PercentageUsedOfQuota. Quota used as a percentage
  • IsHardLimited. Whether the account is blocked due to having exceeded its monthly quota.