Documentation Generator Template YAML File¶
A Documentation Template YAML file (referred to here as the template) is a proprietary format containing the information required to generate the documentation of a connector.
The Documentation Generator is used to create this editable template from the connector’s
adapter.json file. The template is then processed by the generator to create a set of image placeholder and Markdown files. The image placeholders are to be replaced with the output of the Jitterbit Documentation Image Processor and the Markdown files can be edited as required prior to publishing.
Placeholder Text Editing¶
Any location where entries are known to require review will be marked with
PLACEHOLDER_TEXT. These include places where the placeholder text has been used and thus require review. Other places may also be marked with the flag, even if no placeholder text is involved, just to make sure that they are reviewed and checked.
Because of this, you should search for all instances of
PLACEHOLDER_TEXT, review them, and remove them.
The template consists of multiple sections:
- General Connector Metadata
- General Connector Substitutions
- Endpoint Connection Fields
- Activity Sort Order
- Activity Types
Each activity in the Activities sub-section contains these parts:
- General Activity Metadata
- Activity Substitutions
The information in the Activity Sort Order and Activity Types cannot be gleaned from the
adapter.json and so must be manually edited. Once these sub-sections have been completed and the template saved, the template can then be regenerated using the Documentation Generator, which will use these specifications to re-create the appropriate activities.
General Connector Metadata¶
This section consists of the connector name, template version, the path to the source
adapter.json, the directory that the documentation is going to be in, and the Git branch that the
adapter.json was in (if that information was available).
Generally, this section does not need alteration, with these exceptions: -
documentation_directory: This can depend on the spelling of the connector name. -
connector_type: This is typically
public, though some connectors are being released as
private (private agent-only connectors). -
connector_has_verbose_logging: The generator will attempt to determine if this available by searching for a verbose logging class file in the conventional location, and then completing the fields appropriately. -
connector_verbose_logging_level: This can only be determined by asking the connector developer, but typically (and by default) this is
Example from Dropbox:
# Jitterbit Connector Documentation Template name: Dropbox template_version: 2.1.0 source_adapter_json_path: /Users/first.last/Source/dropbox-connector/ui/adapter.json documentation_directory: dropbox-connector github_connectors_repo_branch: master branch connector_type: public connector_has_verbose_logging: false connector_verbose_logging_class: '' connector_verbose_logging_level: DEBUG
General Connector Substitutions¶
Review this section carefully for the correct entries, as these are used for substitutions in the templates that create the individual Markdown pages.
In the case of
A_CONNECTOR_ARTICLE, we are looking for the correct article (
An) that is to be used with the connector name.
In the case of the
CONNECTOR_API_REFERENCE, it can rely on other substitutions (as shown by its use of
<CONNECTOR_API_URL>) and should be edited to be the appropriate phrase when referring to the connector’s API reference.
substitutions: CONNECTOR_NAME: - Dropbox # Connector names are always title case CONNECTOR_NAME_ENDPOINT: - Dropbox # By default, the same as CONNECTOR_NAME; use 'the SAP server' when 'SAP' is not considered accurate CONNECTOR_NAME_FILE_CASE: - dropbox # File case; lowercase with spaces replaced with underscores CONNECTOR_NAME_URL: - https://www.example.com_PLACEHOLDER_TEXT # URL of the product or application of the connector CONNECTOR_NAME_REFERENCE: - '[<CONNECTOR_NAME_ENDPOINT>](<CONNECTOR_NAME_URL>)' # Link reference to the URL of the endpoint or application of the connector. a_CONNECTOR_ARTICLE: - a # Lowercase article 'a' or 'an' used with connector name A_CONNECTOR_ARTICLE: - A # Uppercase article 'A' or 'An' used with connector name a_CONNECTOR_NAME: - a Dropbox # Lowercase article 'a' or 'an' A_CONNECTOR_NAME: - A Dropbox # Uppercase article 'A' or 'An' CONNECTOR_API_NAME_AND_VERSION: - Dropbox REST API vX.X # Generated name and version of the API used for the connector CONNECTOR_API_URL: - https://api.example.com_PLACEHOLDER_TEXT # URL of the API used to build the connector CONNECTOR_API_DEVELOPMENT_REFERENCE: - '[<CONNECTOR_API_NAME_AND_VERSION>](<CONNECTOR_API_URL>)' # Link reference to the API used to build the connector. This can be empty. CONNECTOR_SDK_DEVELOPMENT_REFERENCE: - '[Jitterbit Harmony Connector SDK (v1.0.0)](https://developer.jitterbit.com/connector-sdk/javadocs/)' # Link reference to the Connector SDK used to build the connector. This can be empty. CONNECTOR_API_REFERENCE: - The Dropbox connector uses the [<CONNECTOR_API_NAME_AND_VERSION>](<CONNECTOR_API_URL>). Refer to the API documentation for information on the schema nodes and fields. # Generated text used to describe the Connectors API references. This can be a snippet. GITHUB_CONNECTORS_REPO_BRANCH: - '`master` branch' # Current Git branch or tag; automatically inserted INDEX_INTRODUCTION_SNIPPET: - '' # Optional text after the generated introduction on the index page. INDEX_PREREQUISITES_SNIPPET: - '' # Optional text after the generated prerequisites on the index page. CONNECTION_INTRODUCTION_SNIPPET: - '' # Optional text after the generated connector introduction. This can be a snippet.
Endpoint Connection Fields¶
The structure of this section depends on the connector. Most connectors are configured using a set of fields, though some use dropdown menus, radio choices, and other UI elements.
endpoint_connection_fields: - name: Dropbox App Key description: Enter the Dropbox App Key. PLACEHOLDER_TEXT ui_placeholder: '' type: string - name: Dropbox Access Token description: Enter the Dropbox Access Token. PLACEHOLDER_TEXT ui_placeholder: '' type: string - name: Extra Options description: Enter the Extra Options. PLACEHOLDER_TEXT ui_placeholder: '' type: string - name: Connection Pooling description: Enter the Connection Pooling. PLACEHOLDER_TEXT ui_placeholder: '' type: string - name: Test description: Click to verify the connection using the provided configuration. ui_placeholder: '' type: string
Activity Sort Order¶
The Activity Sort Order section determines the order of the connector activity documentation when they are listed on the
connection.md files and when they are placed in a single Markdown file. Adjust the order of these activities to follow the order of the icons in the
activity_sort_order: - Fetch File - Get File - Process File - Put File
The Activity Types section lets you specify for each activity its type (
target) and if data schemas are provided for the request and response. You can determine the values for the data schema request and response by looking at the images you have created for the final step of each activity:
activity_types: - name: Fetch File activity_type: target data_schemas: request: true response: true data_schema_tables: true - name: Get File activity_type: source data_schemas: request: true response: true search_activity: true data_schema_tables: true - name: Process File activity_type: target data_schemas: request: true response: true data_schema_tables: true - name: Put File activity_type: target data_schemas: request: true response: true data_schema_tables: true
If you have a search or delete activity, they will have additional properties (
delete_activity) set to
activity_types: . . . - name: Delete File activity_type: target data_schemas: request: true response: true delete_activity: true
Each activity is composed of these parts:
The substitutions for each activity are combined with the General Connector Substitutions when creating the Markdown page for an activity.
Substitutions such as the
ACTIVITY_OPERATION_USE_CASE are generated based on the entries in the Activity Types, and become adjusted depending on the
target and which data schemas are available.
For each step of the activity there is a section listing the
snippet, and the fields of the step:
steps: - step_number: 1 name: Enter a Name and Specify Settings description: Provide a name for the activity and ... PLACEHOLDER_TEXT introduction: In this step, provide a name for the activity and ... PLACEHOLDER_TEXT fields: - name: Folder Path description: PLACEHOLDER_TEXT ui_placeholder: '' - name: Name of the File Being Downloaded description: PLACEHOLDER_TEXT ui_placeholder: ''
The values of these properties is created from the information in the
adapter.json and – with the exception of the
step_number – will always require editing.
step_numbers(required) should be sequential and should never need changing.
description(required) is used after each
nameto create a list of steps in the “Configuring a(n) connector name activity name Activity” section towards the start of each activity page.
introduction(optional) becomes the first sentence of each step of the activity.
For each field, the
descriptionfields are used to create the bullet points of the step. They can be snippets. The
ui_placeholderis for reference and is retreived from the
PLACEHOLDER_TEXTis added to generated text for the
introductionto mark it as needing review, with the exception of Data Schema steps, as that text usually is correct as generated.
Example Activity Step Output¶
Assuming the YAML snippet shown above is for the Amazon S3 Get Object Activity, and that the text in the
activity_1_step_1_snippet.md starts with The interface used in this step…, this could be the HTML that is produced:
Configuring an Amazon S3 Get Object Activity
Follow these steps to configure an Amazon S3 Get Object activity:
Step 1: Enter a Name and Specify Settings
Provide a name for the activity and select a bucket to be used. PLACEHOLDER_TEXT
Step 2: Review the Data Schemas
Any request or response schemas generated from the endpoint are displayed.
Step 1: Enter a Name and Specify Settings
In this step, provide a name for the activity and select a bucket to be used. PLACEHOLDER_TEXT
Folder Path: PLACEHOLDER_TEXT
Name of the File Being Downloaded: PLACEHOLDER_TEXT
Alternative Step Content¶
To accomodate different connector user interfaces, the step output contents can be replaced by specifying the contents of a step explicitly. In that case, no generation is performed and whatever is specified for the contents is used directly. Typically this is through the use of a snippet. The minimum requirements are these fields:
step_number: The sequence number of the step.
name: The name of the step.
step_content: Either the content for the step or a snippet reference.
description: The content for the description that appears as part of the bullet list of steps.
- step_number: 3 name: Select an Approach step_content: '--8<-- merge-activity-step-3.md' description: 'Different approaches are supported for merging data to Snowflake. Choose from ... options.'
In the example above, the entire step 3 content is contained in the snippet file
You can use the Documentation Generator to draft initial content for a step, and then copy that portion of the Markdown to a separate file. It can be edited and then referenced as a snippet in place of the original fields. This allows you to continue to use the Documentation Generator to produce and generate all pages without changing the edited content.
Steps With Variable Icons¶
The Documentation Generator attempts to determine the documentation requirements based on the Cloud Studio UI elements described in the
adaptor.json file. In some cases, it does not recognize the elements as they are either new or ones that have not been included. In that case, it will use a
string type of UI element but it will assume that the variable icon is not present in that field. If there are no fields with the variable icon in a step, the note about using the variables in entry will not be included. To force that note to be included, add at the step level an attribute of
has_string_fields: true, such as this:
- step_number: 2 name: Select an Approach description: 'Different approaches are supported for merging data to Snowflake. Choose from ... options.' has_string_fields: true . . .
Successful Documentation Generation¶
The success of the Documentation Generator in creating these sections depends on the connector. There can be connector configurations that are new or unusual that may cause erroneous or unintended results. This can require manual editing of both the template file and the resulting Markdown files. If encountered or you find other issues with the Documentation Generator, please let us know using our contact information at the bottom of the page.
For More Information¶
Though this tool is unsupported, we are happy to receive any feedback, questions, or concerns. You can reach the Jitterbit Documentation Team at firstname.lastname@example.org.