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.

Template Structure¶

The template consists of multiple sections:

• General Connector Metadata
• General Connector Substitutions
• Endpoint Connection Fields
• Activity Sort Order
• Activity Types
• Activities

Each activity in the Activities sub-section contains these parts:

• General Activity Metadata
• Activity Substitutions
• Steps

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

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 and A_CONNECTOR_ARTICLE, we are looking for the correct article (a, A, an, 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_NAME_AND_VERSION> and <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 index.md and 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 assets/<connector_name>-activities.png file:

activity_sort_order:
-   Fetch File
-   Get File
-   Process File
-   Put File

Activity Types¶

The Activity Types section lets you specify for each activity its type (source or 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 (search_activity and query_activity, delete_activity) set to true:

activity_types:
 . . .
-   name: Delete File
    activity_type: target
    data_schemas:
        request: true
        response: true
    delete_activity: true

Activities¶

Each activity is composed of these parts:

• name
• substitutions
• steps

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_INTRODUCTION, ACTIVITY_DESCRIPTION, and ACTIVITY_OPERATION_USE_CASE are generated based on the entries in the Activity Types, and become adjusted depending on the source or target and which data schemas are available.

Activity Steps¶

For each step of the activity there is a section listing the step_number, name, description, introduction, 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.

• The step_numbers (required) should be sequential and should never need changing.

• The description (required) is used after each name to create a list of steps in the “Configuring a(n) connector name activity name Activity” section towards the start of each activity page.

• The introduction (optional) becomes the first sentence of each step of the activity.

• For each field, the name and description fields are used to create the bullet points of the step. They can be snippets. The ui_placeholder is for reference and is retreived from the adapter.json if available.

• The flag PLACEHOLDER_TEXT is added to generated text for the description and introduction to 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:

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.

For example:

    -   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 merge-activity-step-3.md.

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 documentation@jitterbit.com.