ADO Private Repository

Skillable Studio allows you to set Azure DevOps (ADO) as an instruction source, using an external ADO repository. Choosing to leverage this feature means moving all of your content management (including editing) for a lab into ADO. Once you have enabled this instruction source for a lab, the content in that lab will automatically be updated based on the content in the external repository.

External Management Benefits

1. Offline editing - With external instruction management, content is created/edited as part of a structured Markdown file, that can be edited offline using one of the many free or commercial Markdown editors that are available for all mainstream platforms/devices being used today, including Windows, macOS, Linux, iOS, and Android.

2. Revision control - ADO natively supports revision control, which means you get revision control for your content in labs that leverage the integration feature. This allows you to compare revisions, roll back changes, view revision history, etc.

3. Multi-author support - By managing your content in a lab that leverages external instruction source, you can support multiple content authors contributing to the content for one lab at the same time.

External Management Disadvantages

1. Skillable Studio Custom Syntax Unavailable in External Repository - when using an external repository as an instruction source, custom Skillable Studio markdown syntax will not render in the external system. These markdown elements can still be used and rendered in a lab.
   These include:

   • Knowledge block/link

   • Alert block/link

   • Help block/link

   • Hint block/link

   • Note block

   • Copyable text

   • Type text

   • code block modifiers

   • @lab replacement tokens Intellisense

Best Practices

When using an external instruction source, there are a few things to consider.

• The overall size of the repository cannot exceed 500MB.

• Keep your repository as small as possible. Large repositories can possibly present problems. For example, if your repository is approaching the size limit and then multiple commits are made very quickly, some of the commits may not be displayed in the lab instructions.

• We highly recommend using repositories dedicated to your lab content and not mixing other content within these repositories.

• You are able to host content for multiple lab profiles within the same repository, but keep in mind you could eventually need to break this up into multiple repositories if the lab content exceeds the maximum file size per repository. A good rule of thumb would be one repository per course or lab series.

Getting started

For external instruction sources, you will need to have an account ADO and will be prompted to login. If you do not have one yet, you can create an account.

Your repository will need a markdown (.md) file that defines the lab content in Markdown. This file will contain the lab instructions for your lab.

When you configure a lab profile to use an external instruction source, you will be directed to a login page, where you will be asked to allow Skillable Studio permission to access your repositories. Skillable Studio will need access to your email address for push notifications, repository access, and admin permissions to modify web hooks.

Azure DevOps Configuration

If you do not have an ADO account set up yet, you can create an account here.

1. Create a new ADO repository where you will manage your lab content.

2. Create a folder to store your lab instructions and any other files used in the lab.

3. Create a new file in the folder called content.md.

4. If you want to store screenshots for your lab in ADO, create a media folder, inside of the folder created on step 2.

5. If you want to store videos for your lab in ADO, these can be stored in the media folder as well.

If you are moving content for a lab that has
content in ADO, see the Copying Existing Lab Content section below to start that way instead.

To use the markdown document in your ADO repository as the instruction source with a lab profile, navigate to the lab profile you want to configure, then follow these steps:

1. From your lab profile page, select Edit.

2. Select on the Advanced tab, then select Instruction Source.

   

3. Select ADO Repository.

4. If you're not logged in already, you be will prompted to log in to the ADO account that has a repository containing lab content you want to use as an instruction source in the lab profile.

5. Once you are logged into ADO, you will be asked to authorize Skillable Studio to have access to your ADO account. This access is only used to create a webhook so that Skillable Studio can be notified whenever the content in your ADO repository changes. Select Accept to continue with the integration.

6. At this point you will be presented with a list of organizations that are associated with your ADO account. Select select next the organization containing the project file to be used as the instructions source.

7. Select the ADO project that contains your repository.

8. Select the repository containing the markdown file to be used as the instructions source. Repositories without proper permissions will not be displayed.

   When you complete the following step, any existing content in your lab profile will be overwritten, and anything lost will be unrecoverable. If you have content in the lab profile, you can export the lab instructions by selecting the export button at the top of the lab profile details page.

9. Select the markdown file to be used as the instructions source. Once you select the Markdown file that defines the lab content, Skillable Studio will process all lab content referenced by that markdown file and add it into the lab profile instructions. At any point that the ADO content changes, the lab profile will be updated automatically.

10. Once the synchronization process is complete, you will have completed your integration. Select Close to finish the Integration wizard.

11. Your lab profile now shows that instructions are sourced from your ADO repository. Select the Save button at the bottom of your lab profile window to exit the lab profile editor.

Copying Existing Lab Content

If you have a lab that already has IDLx content in Skillable Studio, you can use ADO to manage that content as well. To get this set up you must do the following:

1. In Skillable Studio, navigate to the lab profile that you want to
   manage in ADO.

2. Select Export.

3. In the Export window, select Lab Metadata: Instructions Only and select OK.

4. In the Save dialog, navigate to the location where you want to save the archive file.

The archive file that is saved will contain a content.md file as well as folders for screenshots and videos if either of these were present in the original lab profile. Add these files to the ADO repository that you want to use to manage your lab content, and then proceed to the configure the lab profile to use an external instruction source for ADO.

Activities

Automated and question activities can be used when using an external repository as an instruction source. Activities must be added to the Lab profile and then the Activity Replacement Token added to the lab instructions in the external repository.

To add an Activity to a Lab Profile that uses an external instruction source:

1. Navigate to the Lab profile.

2. Select Edit Instructions in the upper-right corner.

3. Select the Activities menu.

4. Select + New Question or + New Automated Activity.

5. After creating the Activity, copy the Token for the Activity.

6. Navigate to your external repository, and edit the file that is used for the lab instructions.

7. Paste the token in the file, where you want the Activity to be displayed.

The Activity is now part of your lab instructions. Repeat these steps to add additional Activities.