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, Google Drive, OneDrive, SharePoint) Communication with external applications (via URL schemes) Email integration Exchange (email, calendar, contacts) Google (email, calendar, contacts) DocuSign integration Marketing services (MailChimp, MailerLite, GetResponse) SMS integration GitHub integration (for Woodford customizations)

GitHub is a well-known collaboration platform focused on code sharing and version control. Thanks to the integration of GitHub 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 with no data loss. Thanks to GitHub integration, moving projects between organizations is much easier and safer, since multiple organizations can connect to the same backing repository.

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 GitHub with Woodford, you need to know at least the basics of GitHub, 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 GitHub-related buttons appear in Woodford's toolbar when editing an app project.

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

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

The usual workflow of using this feature is that the user configures the connection, then 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 checkout one of the previous versions of the project from GitHub.

Another frequent use case is that a user has to work on a previously prepared project, which is stored on GitHub, 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 GitHub project or prepare different GitHub project to commit.

Configuring a connection

Use this button to set up the GitHub connection.

1. Enter your GitHub credentials:
   • Account 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/repository_name.)
   • Repository Name
   • GitHub Personal Access Token: A link for managing PATs on GitHub is included for your convenience.
     Connecting to GitHub using your email address and password is now obsolete because GitHub has disabled this option.
   • Optionally, check Persist PAT across visits if you want to store the token in your browser.
2. Click Connect.
3. If the connection is successful, you can now select a branch.
4. 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 GitHub 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.

Committing changes

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

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

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 GitHub repository. This can mean:

• restoring an older version of a project
• getting the latest changes from a collaborator
• importing pre-existing project to an organization
• moving project from a development to 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.