GitHub integration

Integration with third-party systems

Resco CRM Connector (web APIs): REST API service OData service Questionnaire OData service Resco Cloud Client (NuGet) Connect Resco Cloud and Dynamics Business Central Power Automate Resco Cloud connector Resco Reports connector Integrations Glossary entry on integration Woodford configuration Documents (Box, Dropbox, OneDrive, SharePoint) Communication with external applications (via URL schemes) Email integration Exchange (email, calendar, contacts) Google (discontinued) DocuSign integration Marketing services (MailChimp, MailerLite, GetResponse) SMS integration GitHub integration (for Woodford customizations)

Git is a well-known version control system. Thanks to the integration of Git into Woodford, you can log the history of changes made in your mobile projects. You can also use this feature to revert back to older versions of projects.

Furthermore, multiple users can now cooperate and store their progress in a single repository without losing data. Thanks to Git integration, moving projects between organizations is much easier and safer, since multiple organizations can connect to the same backing repository.

Supported services

• GitHub
• Azure DevOps (requires Woodford 18.1 or later)

Key benefits

• Logging and auditing of the history of changes, version control
• Restoring previous committed versions
• Getting newer versions
• Importing projects that were created and customized by other users
• Multiple users working on the same project
• Moving the projects between organizations
• Moving projects between development, testing and production environments

Getting started

To successfully use Git with Woodford, you need to know at least the basics of version control systems, particularly the terms repository, commit, and branch. See GitHub Glossary for definitions.

You may also want to complete this simple exercise Hello World.

Prerequisites

Woodford writes into the Projects folder of the selected branch of the GitHub repository. The default branch is master. This needs to be taken into account especially when using preexisting repositories. In general, it is recommended to prepare a separate repository for each CRM organization and to use it only for Woodford projects.

User interface

Three Git-related buttons appear in Woodford's toolbar when editing an app project.

• Commit – for exporting a new version of the mobile project to Git (also located in the project detail page)
• Checkout – for importing a version of the mobile project from Git
• Configure – for setting up the connection to Git

The Commit and Checkout buttons remain inactive until you configure a connection to a Git account. The Commit button also needs a mobile project to be selected to become active.

The usual workflow for using this feature is that the user configures the connection and commits the project after each set of changes. From time to time, the user can make a mistake or customers change their mind. Then, they check out one of the previous versions of the project from Git.

Another frequent use case is when a user has to work on a previously prepared project stored on Git, for example, in a company account. The user configures the connection and checks out the project. After some work, they can commit their changes back to the Git project or prepare a different Git project to commit to.

Configuring a connection

Use the Configure button to set up the Git connection.

1. As Provider, select either "Azure DevOps" or "GitHub".
2. Enter your Git credentials: Account Name, Project Name (Azure DevOps only), and Repository Name.
   (Your account name can be either the name of a personal account or the name of an organization’s account. To decide which account name to fill in, simply open the page with your repository and check the full name of the repository. It is in a format: account_name/project_name (Azure DevOps only)/repository_name.)
3. Git Personal Access Token: Generate a PAT in your Git and copy it here. A link for managing PATs is included for your convenience. See GitHub tokens for more information.
   Connecting to GitHub using your email address and password is now obsolete because GitHub has disabled this option.
4. Optionally, check Persist PAT across visits if you want to store the token in your browser.
5. Click Connect.
6. If the connection is successful, you can now select a branch.
7. Click Save.

You can either work with the default branch, master, or you can create a new branch.

If you don't let the token persist across visits, your Git connection is stored in browser session storage, and thus it is persistent until the tab is closed. When you close the tab, all buttons stay enabled. However, you must enter the PAT again before performing Commit or Checkout operations.

When you opt to store the token in your browser's local storage, it will be saved there also for your future connections.

PAT tokens

Personal access tokens (PAT) are an alternative to using passwords to authenticate with Git.

GitHub

Woodford is compatible with both classic tokens and the (newer) fine-grained tokens. Tokens are managed in the Developer Settings of your GitHub account. Generate a new token and mind the following requirements:

• For classic tokens, select "repo" as the scope.
• For fine-grained tokens:
  • Set Repository access to either "All repositories" or "Only select repositories" (and choose the appropriate repositories).
  • Under Repository permissions, grant read and write access to "Contents" and "Pull requests".

For more information, see Managing your personal access tokens at GitHub Docs.

Azure DevOps

Tokens are managed in your user settings: https://dev.azure.com/<account>/_usersSettings/tokens.

Committing changes

After changing a mobile project, users can commit the changes to Git.

1. We strongly recommend to save the changes in Woodford before the commit.
2. Click Commit. In case of unsaved changes, a warning is displayed.
3. Enter the Description of your changes and click Commit again.
4. Wait until your changes are securely stored in Git.

The Commit button is available on multiple Woodford subpages, but functions identically: it saves the entire project configuration.

Checking out a version

A check-out retrieves a particular version of the project from the repository. This can mean:

• restoring an older version of a project
• getting the latest changes from a collaborator
• importing a pre-existing project into an organization
• moving the project from a development to a production environment

Proceed as follows:

1. If you want to overwrite an existing app project in Woodford, select the project.
2. Click Checkout.
3. Select a project and click Select. If you have previously selected a project, it will be selected by default.
4. Select a version to retrieve (for example, the latest) and click Checkout.
5. Wait until Woodford finishes loading project data.
6. If you selected a project in step 1, you have one more chance to reconsider:
   • Click Overwrite if you want to overwrite the project.
   • Click Create New to use the project data from GitHub to create a brand new app project.
   • Click Cancel to end the checkout without changes.

Examining the changes in GitHub

You can review the changes in GitHub.

1. Using a web browser, log in to your GitHub.
2. To see all commits, click the link highlighted in red.
3. To see or switch branches, use the links highlighted in purple.
4. To see all differences between the selected and the previous version, click on a particular commit.

Note	If any files have been deleted in the commit, each deleted file will be shown as a separate commit. The commit message (description) is shown only next to the changed files. This is due to the versioning technology GitHub uses.

Folder structure in GitHub

Your first commit of an app project creates a folder with its name in GitHub's Projects folder. Each project has its own folder.

A project folder contains every file of that specific app project: list of entities, server configuration, and app project's settings.

The most important sub-folders are:

• Configuration: contains the configuration files (for example, SyncFilter.xml) along with localization files
• Controllers: contains all files representing forms, lists, and charts together with style and themes

Additional sub-folders are created when necessary:

• Images: stores custom images
• www: contains custom HTML files

We strongly discourage direct editing of these files! In rare cases, editing files in the folders www and Images can be useful; however, editing other files can lead to severe problems within the mobile project.

GitHub limits

Some repository resources can be quite large, requiring excessive processing on GitHub. Therefore, there are limits below affect GitHub and its API. See Repository limits on GitHub Docs. Very large Woodford projects might exceed these limits.