snapADDY-mapping-toolkit

This VS Code extension provides programmatic language features to assist in the creation of snapADDY CRM mappings.
This documentation assumes, you already know the basics of snapADDY CRM Mappings.

Based on the original VS Code json-language-features

Contents

1. Feature Overview
2. User Guide
   1. Settings
   2. Authoring Features
   3. Revision Explorer
3. Recommended settings for VS Code
4. Recommended extension
5. Dev notes

Feature Overview

• Introduces new language: *.smf (snapADDY mapping format)
• Document validation
• Formatting
• Snippets
• Extended syntax highlighting
• Mapping generation
• Commands:
  • Open FieldDefinitions
  • Open Customer Folder
  • Add Field
  • Remove Field
  • Validate Mapping
  • Validate VisitReport
  • Build Components

User Guide

Settings:

• RevExplorer: Toggle the revision explorer
• Customer Path: Path to customers spec files
• Environment: Select the desired environment
• ProductionToken: The API Token for the production environment
• StagingToken: The API Token for the staging environment
• DevToken: The API Token for your development environment
• DevName: The name of your development environment
• Format: Toggle the formatter for SMF files
• Trace: Toggle debug tracing

Authoring Features

Globally available snippets

• base: creates the root object
• documentation: creates a documentation template (to be used inside root.documentation)
  Structure:

{
  "documentation": {
    "YYYYMMDD-Name": {
      "[location of changes]": {
        "[added|changed|removed]": [
          "description of the change"
        ]
      }
    }
  }
}

• function snippets as escaped JSON (genderMapping, salutationFunction, getVRNote, countryMappingDE, countryMappingEN)

Schema validation

The schema validation helps you spot errors in your mapping structure and validates your mapping. It also supplies some documentation for most properties which are available on hover.
As of now you can still publish invalid mappings (as longs as it's valid JSON). The validation is not entirely complete, but supports all major CRMs (Dynamics 365, Hubspot, Pipedrive, Salesforce, SAP C/4HANA, SugarCRM, Suite).

Autocomplete

As part of the validation schema this extension helps by suggestion keys from the schema as well as complete snippets at several locations. Available snippets are:

• complete CRM templates
• separate component templates (see also component generation)
• duplicate check pipelines (currently not available for Pipedrive)
• minor/repetetive parts like dropdown options, labels

Component Generation

The extension provides a command, to automatically generate components field scaffolding from the existing field mapping. To generate components, open the command line (Ctrl + Shift + P) and search for snapADDY: Build Components. It will then guide you through the selection of the relevant section. If your cursor is already placed in the components section which you want to generate the code for, it will find the path for you and ask for confirmation.
The generated code is placed in your clipboard, so you just need to paste it into the fields: {} property of the desired entity.

Revision Explorer

The revision explorer must be enabled in the settings and requires an API token for at least one environment (production, staging or dev). It syncs with the snapADDY backend and enables you to read and update revisions.

Title Bar

1. create new empty revision
2. refresh revisions

Revisions

1. Checkmark (✓) marks approved revision
2. Pen icon (🖊) marks revisions you can edit
3. (active) marks the currently active revision

Hover Options

1. Activate a revision
2. Metadata such as creator, last editor and last change date

Context Menu (right click)

1. Duplicate the selected revision
2. Update the selected revision with the content of the editor, that is currently active
3. Delete a revision

Options are only available if applicable (e.g. you can't delete an approved revision etc.)

Recommended settings for VS Code

Alternate color scheme to easily distinguish between JSON and embedded JS. Add those to your settings.json

{
  "editor.tokenColorCustomizations": {
    "textMateRules": [
      {
        "scope": "string.quoted.double.json",
        "settings": {
          "foreground": "#ffb84edd"
        }
      },
      {
        "scope": "constant.character.escape.json",
        "settings": {
          "foreground": "#ff4500",
          "fontStyle": "bold"
        }
      },
      {
        "scope": "support.type.property-name.json",
        "settings": {
          "foreground": "#0496ffe0"
        }
      },
      {
        "scope": "entity.name.function.js",
        "settings": {
          "fontStyle": "italic"
        }
      }
    ]
  }
}

Recommended Extensions

• Transformer - Useful functions like transforming text or code to JSON string arrays

Dev Notes

see dev docs