Jitterbit Cloud Studio Connector Documentation Generator¶

Introduction¶

The Jitterbit Cloud Studio Connector Documentation Generator assists in the creation of documentation that Jitterbit publishes on each of its connectors. The Documentation Generator is used to create Markdown files that document a connector, derived from the connector’s adapter.json file that defines the connector’s UI in Cloud Studio.

The Documentation Generator is first used to create an editable template file from the connector’s adapter.json file. This template file is then edited by you to specify additional properties that are not in the adapter.json. The template file is then regenerated, and then you can edit it further to add more details on the connector.

In the final step, the template is processed by the generator to create a set of Markdown files and image placeholder files. The image placeholders are to be replaced with the output of the Jitterbit Documentation Image Processor and the Markdown files are to be edited as required prior to publishing.

It’s assumed that you are familiar with Cloud Studio, its connectors, the Connector SDK and the format of the adapter.json file, and the general structure of the documentation of a Cloud Studio connector, as can be seen for the individual Cloud Studio connectors.

We recommend reading these documents in their entirety in order to learn of our intent and approach in developing connector documentation:

• Documentation Generator: (The document on this page.) Describes the intent and the controls of the Documentation Generator.
• Documentation Generator Template YAML File: Describes the format and structure of the Documentation Template YAML file created by the Documentation Generator.
• Documenting the Dropbox Connector: Demonstrates how to document a connector using the Documentation Generator.

Download¶

The Documentation Generator is available for the macOS and Windows operating systems. Download an appropriate installer package from these links:

• macOS

• Windows

See the release notes for details of changes in the application.

Installation¶

The application is packaged using an installer appropriate for the operating system. Open the installer and follow its prompts to install the application.

If you are installing on macOS, you may receive a warning message about the installer and be required to approve the installation in the Security & Privacy panel of the macOS System Preferences, as shown in this example for the Project Reporter tool:

Intent of the Tool¶

The intent of the tool is to create these artifacts:

1. A connector documentation template file, in YAML format, that reflects the structure of the adapter.json file used to define a Jitterbit Harmony Cloud Studio connector.

2. A set of Markdown files and image placeholders that document a connector based on that connector documentation template file. The naming of the image placeholder files is designed to work with the Jitterbit Documentation Image Processor.

If used as intended, all of the source material required for documenting a connector can be provided in the connector documentation template file (referred to as the template file) and the final documentation can be generated from the template file by the generator.

When documenting a connector, it is useful to include if connector activity configuration values can be overridden in the request structure (or not, if that is the case). In general, any value in the activity configuration can be overridden in the request if there is a matching entry in the request data schema structure. As this behavior depends on the connector, this has to be determined either by discussing with the connector developer or by reviewing the connector source code.

Usage Overview¶

Over the course of creating a completed set of Markdown and image files, the tool will be used multiple times, and the generation of the Markdown files can be required repeatedly. This is an overview of the steps; detailed steps are included in Documenting the Dropbox Connector:

1. You use the Documentation Generator to generate a connector documentation template YAML file (a template file) from a connector’s adaptor.json file.

2. You then can generate an initial set of Markdown files and image placeholder files.

   These image placeholder files will be named to match the screenshots that need to be created from Cloud Studio and then processed using the Image Processor.

3. You can now take the screenshot images of the connector, and using the Image Processor, rename them to the correct names. You need to review the images and determine for each connector activity how it is used and which data schemas are provided.

   • Is an activity intended to be used a source or a target?
   • Which request and response structures are provided by an activity?

   The main image for the connector should show all of the available activities. From this image the order for the activities can be determined.

   With this information, you can then edit the template file and set the appropriate entries.

4. Edit the template file:

   • Specify general information that pertains to all connector activities.
   • Specify the order of the activities (to match the order as shown in the connector image)
   • Specify for each activity which data schemas are displayed in their final step (as shown in the final step of activity).

5. Regenerate the template file (using the settings provided in the previous step) to create the correct entries required for each activity.

6. Now that the template file has the correct entries, edit the template file a second time to set information required for each activity, now that the template file has the correct entries that can be completed. This edit of the template file is to remove any fields where placeholder text was used and to add any missing information.

7. Generate a final set of Markdown files and image placeholder files.

You can generate Markdown files from the documentation template either as a set of files or as a single Markdown page. In both cases, the image files will be located in a separate assets directory.

To finish and install the documentation, there are controls to copy any existing image files into the generated documentation and to install the completed set of Markdown and image files.

Operating the Tool¶

Start the tool as you would any other application. The tool runs in a single window. The Help menu in the tool links to this documentation and the Jitterbit Developer Portal and checks for updates. Menus are not used in the application except for the “About” dialog, the Help menu, and exiting the tool.

Tool Components¶

The tool consists of three main panels: a top panel and a series of numbered panels. The numbered panels below the top panel reflect the order of how the tool is intended to be used, though you may find yourself going back to a previous step to redo or regenerate a file.

Top Panel: Specify Connectors Documentation Source Directory¶

The top panel shows the current directory used for what is considered the documentation directory for all connectors:

In that directory will be placed the generation directory, named generation. The button Browse for Source Directory for Connectors Documentation browses for the directory of the connectors documentation source (or where it will be.) The generation directory, its documentation templates, and generated documentation will all be created in this directory.

1.0 Create Connector Documentation Template¶

The Create Connector Documentation Template panel is used to load an adapter.json and create a connector documentation template YAML file:

• Connector: Displays the name of the current connector whose adapter.json is loaded.

1.1 Specify Connector Adapter JSON¶

Use these controls to select and view an adapter.json file:

• Connector Adapter JSON: Displays the current adapter.json that is loaded.

• Browse for Connector Adapter JSON File: Browses for a JSON file and sets it as the current connector adapter.json file.

• Open Adapter JSON File: Opens the current adapter.json in the system editor that is designated for JSON files.

• Favorite Connectors: A dropdown menu that can be configured (with the Add as Favorite, Remove as Favorite, Clear Favorites) to link to particular connector adapter.json files. As these are referenced by name and not by path, attempting to load two different versions of the same connector adapter.json file will not work with the dropdown as it can’t distinguish between them.

1.2 Create Connector Documentation Template YAML File¶

Use these controls to create the documentation template file:

• Create Connector Documentation Template YAML File: Creates a template YAML file based on the structure of the adapter.json. The details of the template YAML file are discussed in Connector Documentation Template YAML File.

• Suppress Warnings: When selected, no warning will be displayed if an existing file will be overwritten. Disable if you prefer to be warned before overwriting.

2.0 Generate Documentation¶

The Generate Documentation panel is used to load a connector documentation template YAML file, regenerate it based on its contents, and to create Markdown and placeholder image files:

• Connector: Displays the name of the current connector whose template YAML file is loaded. (When a template YAML file is created by the previous section, it will automatically be selected and the connector name in sections 1.0 and 2.0 will then match.)

2.1 Specify Documentation Template¶

Use these controls to select, edit, and regenerate the documentation template file:

• Browse for Documentation Template: Browses for a YAML file and sets it as the current documentation template file.

• Edit Documentation Template: Opens the current documentation template file for editing.

• Regenerate Documentation Template: Regenerates the current documentation template file by applying the activity types to the activities. See the section on Regeneration for details on what this does.

2.2 Generate Markdown from Documentation Template¶

Use these controls to generate the Markdown and image placeholders files:

• Generate Markdown from Documentation Template: Loads the current documentation template file and generates Markdown and image placeholders files into a directory of the generation directory.

• Suppress Warnings: When selected, no warning will be displayed if an existing file will be overwritten. Disable if you prefer to be warned before overwriting.

• Single Page: Generates the documentation as a single Markdown file rather than as a set of individual Markdown files. (The placeholder image files will still be created as individual files to reflect how the files are created and used.)

• Include Configuration Images: By default, only the index page’s connection image showing the connection and its activity blocks is included. If this is selected, images will be included for all configuration pages, including each activity step and the operation examples. If this is not selected, the descriptive text that normally precedes an operation example image (“A typical use case…”) is not included.

2.3 Install Documentation and Image Files¶

Use these controls to both copy existing images into the generated documentation and to install the generated documentation:

• Copy Images of Current Connector to Generation Directory: Copies images in the connectors documentation source directory to the corresponding generation directory for the current connector, as set by the current documentation template file.

• Copy Generated Documentation into Connectors Documentation Source Directory: Copies the generated Markdown files (and optionally the image files) to the corresponding connectors documentation source director.

• Copy Images from Generation Directory: By default, images in the generation directory are copied to the corresponding connectors documentation source directory.

Note that copying is additive only. If you have a file (either Markdown or an image file) in a <connector-name> directory in the documentation directory that does not exist in the matching generated/<connector-name> directory of the documentation directory, using these controls will not remove those files. You will need to manually remove them.

Help Link¶

A link to this page is available by selecting it from the Help menu or using the F1 key shortcut.

Documentation Template YAML File¶

The Documentation Template YAML file is a proprietary format containing the information required to generate the documentation of a connector.

See Documentation Template YAML File for a description of its structure and how to edit it.

Regeneration¶

As the creation of the documentation template file does not have all of the information required to create the documentation, the documentation template file must first be edited and then regenerated before the final edits and the generation of the Markdown and image placeholder files.

The first edits are to set the order and type of the connector activities, and to specify if data schemas are provided for each request and response.

See the Template File for details on how and what is needed to be edited before regeneration can take place. The Dropbox Connector tutorial shows an example of editing the template file and what happens as a result of regeneration.

The regeneration control (Regenerate Documentation Template) is located in section 2.1 of the Documentation Generator:

Removing Placeholder Text¶

When initially generated by the Documentation Generator, the documentation template file contains references to the placeholders in the connector. These are flagged with the text PLACEHOLDER_TEXT to indicate that they need to be reviewed, removed, and the text that is with them edited or expanded as appropriate. This PLACEHOLDER_TEXT is used wherever it seems appropriate that review is required, even if placeholder text was not actually used.

See Placeholder Text Editing for details on editing the documentation template file and how to remove these flags.

Release Notes¶

2.4.0

• Updated the application icons to use the new Jitterbit logo and to correct an issue with the macOS icons being too large.

2.3.0

• Fixed issues with the generated documentation and its links to support the new Success Central website.
• Improved the build infrastructure to use specific Python libraries.

2.2.1

• Fixed an issue with documentation template file files that have description fields that are empty. They no longer break generation. Instead, a warning message is logged and displayed at the end of generation indicating which fields have no descriptions. Though all fields should have a description, this is left up to the user to resolve.

2.2.0

• Fixed an issue with adaptor.json files that are malformed and have single page elements mixed with pagination. Such a connector will not render correctly in the Cloud Studio UI and a fatal error was previously thrown in the Documentation Generator when such an adaptor.json was opened. The Documentation Generator now loads such an adaptor.json, records the errors it finds for an activity in a new errors field in the YAML file it creates, and warns that errors were found.

When Markdown is generated from such a YAML file (a file containing completed errors fields), a message is displayed in the completion dialog warning that the Markdown was built from a file containing known errors and lists the particular activities where the errors were found.

• Language corrections and changes were made in the output.

2.1.1

• Fixed an issue with activities that did not use pagination and with the regeneration of activities that had no steps. Though there probably should be no cases of activities with no steps, they are accepted for regeneration of the documentation.

2.1.0

• Step content can be specified directly. If the key step_content is in the YAML file for a step, only the name, description, and that content (which can be a snippet) are used.
• In the template for connection.md, updated the label to read Connection Name.
• Improved the messages returned when generating documentation to specify where placeholder text was found or used and where to search for it to fix it.
• Added to the “Query String” description.
• Verbose logging can now be specified to be generated on the index page. It will be generated in new template YAML files automatically by looking at the connector source code and finding the class name.
• Text can be added after the generated prerequisites on the index page by using the new INDEX_PREREQUISITES_SNIPPET subsitution.
• Single character literals such as / are no longer enclosed in parentheses.
• A query image has been removed from the generated documentation.
• Fixed an issue with Cloud Studio UI elements that the Documentation Generator is unfamiliar with. These are now regarded as strings without variable support unless that is explicitly specified in the YAML file.

2.0.0

• Shortened the labels of the warning checkboxes and the single page checkbox.
• Added trailing punctuation to the comments in the documentation template YAML file.
• Added a checkbox to specify if configuration images are to be included. By default they are not included, with the exception of the index page’s connection image, the refresh icon image, and the variable icon image, which are always included.
• Changed the JSON loader library to one that supports JSON5, which allows trailing commas in lists and maps.
• Added new and revised substitutions to the template YAML file. These are breaking changes. All documentation template YAML files need to be regenerated before using for generation.
• Replaced the use of “edit” and “base” templates in a single file with a single template in a single file.

Revised substitution:

• CONNECTOR_NAME_ENDPOINT_URL has been renamed CONNECTOR_NAME_REFERENCE

New substitutions:

• CONNECTOR_API_DEVELOPMENT_REFERENCE: Link reference to the API used to build the connector. This can be empty.
• CONNECTOR_SDK_DEVELOPMENT_REFERENCE: Link reference to the Connector SDK used to build the connector. This can be empty.

• INDEX_INTRODUCTION_SNIPPET: Optional text after the generated introduction on the index page.

• Fixed an issue where the UI was not correctly updated when an adapter.json file could not be loaded.

• Fixed an issue where an empty entry in the documentation template YAML file caused an exception during generation. The empty entry is now considered to be an empty string.
• Fixed an error when generating a query activity and its second Build Your Query step.

1.5.2

• Fixed an issue with the use of CONNECTOR_NAME_ENDPOINT_URL in the index.md page template.

1.5.1

• Updated output generation to match the current style for connector documentation. This will not always work with any previous template YAML files, and any existing template YAML file should be recreated from the original connector adapter.json files and then updated as required.

1.4.2

• Initial public release of the application.

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.