Important Notice: Blog moving to the new Developer Community of Practice in the Brightspace Community sitePosted: 2014/11/06
Back in August, we announced the launch of the Brightspace Community site and gave everyone the heads up that the Developer Community would eventually be transitioning over to that site. That time is upon us!
As of Monday, November 10th this blog and the ValenceUsers forums will be hosted within the new Developer Community of Practice (Dev CoP) site. (Note: This link will become reachable as soon as the site goes live.)
- Blog posts have been migrated to the new site, and the blog URL will automatically redirect to the new blog after the launch.
- The ValenceUsers forums will be locked on Sunday, November 9th. Forum posts will be migrated to the Dev CoP site in time for launch – including anything posted in the next few days. You’ll be able to search for pre-existing topics and pick up conversations where you left off.
- The GitHub org that hosts the Valence SDKs and Samples will be renamed to Brightspace. You’ll need to update any automated processes watching these repos to use the new org name. For example, https://github.com/Desire2Learn-Valence/valence-sdk-dotnet will become https://github.com/Brightspace/valence-sdk-dotnet.
- Updates to the documentation site will go live on Monday as well. For example, samples documentation from the Valence documentation site has been migrated to the new blog to ensure all related content is stored together.
Developers want a quick and easy way to try an API call and see the result without having to build code around it. Or, if they’re troubleshooting code from an existing project, they want a chance to try out the API call in isolation to help them narrow down whether the issue is with the call they’re making or how they’ve implemented it in their code.
The API Test Tool (based on the Getting Started Sample) is a utility that streamlines the authentication process and allows developers to get down to the business of trying out the Valence Learning Framework APIs.
The API Test Tool runs in a browser and provides an interface to point to a D2L Learning Environment (LE), supply an App ID/Key pair, and log in with a given user account. Once authenticated, you can make calls using a straightforward interface.
By default, this utility points to a sample LE identified in the Host field. You can update this field to point to any LE that is accessible to the API Test Tool. For example, if you’re using the online version of this utility, it must be able to reach your target LE (and vice-versa) without being blocked by an intervening firewall.
The utility uses a default App ID/Key pair that is configured for the sample LE. You’ll need to update these values to match an App ID/Key pair for an app that is registered to your target LE instance. For more information on the App Registration process, check out the FAQs and Best Practices. For environments at 10.3 SP13 or higher, check out the new App Reg Process.
Note: You can use the API Test Tool to help rule out issues with your App ID/Key pair. For example, if your code is giving you a 403 Invalid Token error, you can use the API Test Tool to verify if the App ID/Key is working properly in another context. If the App ID/Key pair is working with the API Test Tool, then you should double-check that you’re using the same App ID/Key pair in your code. If all is well, you can move on to investigate other pieces of the ID/Key Authentication process confident that your App ID/Key is working as expected.
Make a GetVersions Call
At this point, you can click the GetVersions button and then click Submit to receive a Response showing a list of supported API contracts on the target LMS. The GetVersions API call does not require an authenticated user. You’ll need this information to ensure you’re calling an appropriate version of each API route.
Authenticate and Experiment with API Calls
Click Authenticate to be redirected to the D2L Learning Environment login screen on the target environment. Log in with your target user account. (If using the sample LE, be sure to make note of the sample user credentials displayed in the API Test Tool interface before clicking Authenticate.) Once authenticated, you’ll be redirected back to the API Test Tool interface. Notice that the User ID and User Key fields are now visible and populated.
Note: You can use the API Test Tool to retrieve user tokens for an application that runs headlessly under a dedicated service account. For more information on designing headless applications, check out this relevant forum post and search for other related posts.
Once authenticated, you can try some pre-configured API calls using the available WhoAmI and Create User buttons. If you’re using the sample account for the sample LE, the Create User call won’t execute successfully: the sample user doesn’t have sufficient privileges to create this type of data. This is a great example of how permissions limit data access via the API.
Now you can try pasting in any other API call that you’d like to test. You’ll need to select the appropriate action by selecting the Get, Put, Post, or Delete radio button. When appropriate, you’ll use the File input mechanism or enter valid data in the Data field and then click Submit to see the Response.
The API Test Tool is available online or as a PHP sample. Use the online sample to work with the sample LE or to point to any D2L LE that is visible thru the internet. Use the PHP sample if target environment is located behind a firewall. You can also modify the sample code to extend its capabilities to fulfill your own development and testing needs.
The API Test Tool for the PHP platform has the same requirements as the PHP client library.
- Download the latest version of the API Test Tool and unzip it to a local directory inside your webserver’s document tree.
Note: In most Unix systems, you can add the contents to /var/www, or create a virtual host; in Windows, you can create a public profile in IIS.
- Point a browser to the sample by navigating to http://yourServer/docRoot/util-api-test-tool/index.php.
This utility is like a Swiss Army knife for developers – whether you’re working with the Learning Framework APIs for the first time or debugging code from an old project. Give it a try – either online or in your own environment. If you’ve got any tips for using this utility or if you’ve extended this utility, add a post in the ValenceUsers forum describing what you’ve achieved.
Keytool will be unavailable tonight at 5pm Eastern for approximately one hour. Please avoid trying to access Keytool to register applications during that time. We expect it to be fully online once the maintenance is complete.
Earlier this year, D2L ran its second annual company hackathon – an innovation event aimed at getting the creative juices flowing for employees. I participated in the event, and then followed up with two of the organizers – Sean Yo, Technical Product Manager and Carmen Zannier, Development Manager – to get their feedback on what inspired the event, what it took to make it happen, and their advice to help others host a similar event in their own organizations.
Why are we talking about this event now? As you’ll see below, an important improvement to the Valence developer experience came about as a direct result of D2L Hack 2014. Read on for more info and to hopefully be inspired to run or participate in your own hackathon.
How would you describe the concept of D2L Hack 2014? What inspired you to run this event? What were the goals of the event?
Sean: For me the D2L Hack 2014 (a.k.a The Mighty Hack) is all about helping the people who build software together at D2L have fun and be awesome. We’ve been working hard at living Agile values in how we build our software; one of the keys to that is to self-organize our work. While we’re making progress, we have a lot of legacy code and organizational history. The D2L Hack is a time to take a week off from our normal constraints and live the dream – build what you want with who you want.
I’m really inspired by Mats of Ruby fame who describes his purpose in creating the Ruby programming language as “help every programmer in the world to be productive, and to enjoy programming, and to be happy. That is the primary purpose of Ruby language.” For Mats, systems need to emphasize human, rather than computer, needs. D2L Hack 2014 is all about people and giving them the space and time to be joyful and productive. Our goal isn’t to ship software or file patents – if those things can happen that’s great. Our goal is to connect with the thrill of working with a new team, exploring new ideas and hacking as hard and as long as you want because you’re so excited about the work.
What were some of the memorable moments from the event? What were the highs and lows of running and participating in this style of innovation event?
Sean: There are bursts of activity around pitches and groups getting together and setting up their work spaces and war rooms and then it’s very quiet. Heads down – cranking out code. Walking around the office and seeing clusters of people huddled around new workspaces – people from all over the building cross-pollinating and being awesome together was amazing. Definitely one of my favorite memories. I also did some coding – I did a small solo project. I really like doing the things I advocate – it was fun to get my hands dirty in some code. As someone who doesn’t code for a living anymore, having some time – however brief – to sit and code and benefit from the amazing generosity of the engineers at D2L who gave me more than a little help was inspiring.
This was the second time we’ve run this event and the first time it was a bit like “Hey! Let’s do a Hackathon…SWEET!”. It was a ton of work and was crazy awesome. Since we had quite a bit more time to think about the event this time around, we ended up being quite ambitious with our planning. Above and beyond what we did the first time, we had catering and t-shirts, used a new version control system, set up online documentation and discussion to facilitate the event, tracked our projects in our Work Management system, documented time and features, doubled our number of awards, added prizes for awards, invited colleagues from across the organization to judge our awards, and had people participate in our remote offices across 6 time zones. We had at least one serious crisis a day that left us in sheer panic. But we pulled together, figured it out and moved forward.
What were the prize categories for the event?
Carmen: We had 20 different awards, and 10 of them were directed to projects that supported our Services division. They each came with a super cool poster that teams could pin up at their desks, as well as a cash prize for a hackathon team lunch.
Here is an sampling of some of the prize categories:
- People’s Choice: Voted by the people, for the people, by the people for…
- Most Useful: This project provides exceptional value to the customer and/or D2L.
- The Bleeding Edge: Technical achievement- forward thinking way beyond reality- the future is now.
- Hitting The Moon: A.K.A we failed in our scope but look what awesome things we learned!
- Most Likely to Ship: This thing is so dang good, it’s ready to go today.
- Support Superstar: Customers lives are changed for the better – a shining star achievement.
- Bug Buster: Most valuable contribution to the extermination of Services backlog infestation.
- Less is More: It’s always harder to take away. Congratulations on making a complicated thing simple.
How did the Valence development platform factor into this event?
Sarah-Beth: At least 30% of the projects that came out of the D2L Hack touched Valence in some way. Some consumed Valence Learning Framework APIs to build end-user apps, others experimented with building new APIs or improving upon infrastructure underpinning the development platform.
One such project was called Integrate in an Instant. (Full disclosure: This was the team that I participated on.) To give you some context, as Valence-savvy developers are well aware, the Valence Learning Framework APIs use an ID\Key Authentication mechanism. Every app developed using Valence – whether by a client, Partner, or D2L developer – must be registered in order to generate a unique App ID\Key pair. The process for acquiring those keys has left something to be desired. A team formed around the goal of eliminating the major pain points – long delays in approvals, rejected requests due to human error, and wait times for synchronization of approved apps.
The result of 5 days of research, coding and testing was a prototype of an improved app registration mechanism that allows developers or administrators to register apps directly in a target Learning Environment. The benefits – saving manual effort for approvals, improving productivity for clients & Partners, and reducing the chance of human error – resonated within the company. In fact, the project won two awards – Less is More and Most Likely to Ship. To make good on the latter award, the project was added to the backlog for a development team, and the prototype was re-engineered into production-quality code that recently shipped to customers. This is just one example of how a D2L Hack project resulted in a direct impact to D2L Clients and staff.
What advice would you give to anyone considering a similar event on their campus or within their organization?
Sean: The most important thing is to be clear on why you’re doing this. It won’t work if it’s a bug blitz in disguise or if it’s constrained to a specific and narrow problem. These events are about self-organized work, it’s about re-energizing development teams by letting them imagine it, pitch it, build it and then demo it. Having a theme is fine – in fact it’s useful. Just don’t lose sight of the fact that this is an investment in talent and culture – it isn’t a way to produce shippable code. In fact, if awesome ideas come out of a hackathon, make sure it’s re-engineered from scratch. Commit to Hackathon code being for the Hackathon only – besides, the rework will be simpler, more elegant and just better.
This event is crazy awesome – and that means it’s a crazy amount of work. To be fair – we did run ours for 5 days, which is…well…crazy. Regardless of the length of the event, a great hackathon takes preparation and planning. Here are a couple of useful resources to look at to get a sense of how to run a hackathon of your own:
Oh – and don’t run out of snacks. Srsly. This is what we got for the D2L Hack 2014.
A D2L client and Valence Community Member has a project in mind, but her team doesn’t have the bandwidth to tackle the project right now. Instead, she’s putting the call out to the wider Community to find a developer interested in a small, freelance opportunity.
From Storie Walsh:
We are looking to include a widget on our course homepages that provides profile information about the instructor. Preliminary research reveals that this project should be possible using a Widget Remote Plugin, LTI and the Valence Learning Framework APIs. We’re looking for a developer who can gather detailed requirements, design and build using the available technologies, and provide us with a working solution to deploy in our environment. For more detail or to express your interest, please contact me via email.
Note: This post is being made on behalf of the requester and in the interest of facilitating member-to-member collaboration. D2L is in no way endorsing this opportunity or endorsing any respondents to this request.
What do you think?
Are you interested in seeing more of these sorts of opportunities shared in the Valence Developer Community? Share your opinions in the ValenceUsers forum.
Do you have a similar request that you’d like to share? Contact us via the Valence email account to share the details and we’ll look into sharing your opportunity.
Note: The functionality described in this post is available in 10.3 Service Pack 13 and the 10.4.3 release for Continuous Delivery clients. Contact your Account Manager or Technical Account Manager to schedule the appropriate update to your environment to gain access to this new functionality.
Introducing app registration via Manage Extensibility
We’re pleased to announce the latest improvements to the app registration process, which resolves a time-consuming bottleneck that has been on the minds of Development Community Members and D2L Staff.
The Manage Extensibility admin tool in the Learning Environment gives LMS Admins a view of the apps that are currently registered against the environment. The list includes Universal apps released by D2L or our Partners, and Limited apps registered by the institution or its integration providers. The Manage Extensibility tool makes it possible to selectively disable apps so that they can’t connect to your environment. With this update, the Manage Extensibility tool provides the ability to register new apps.
To register a new app, click the Register an App button to launch the Register an Application form. This form is a simplified version of the Register New Application form in Keytool. One notable exception is that you no longer have to specify your environment’s LMSID because this value is inherited based on the environment you’re logged in to.
Complete the required fields – including specifying the new Trusted URL value – and then click Register Application.
The LE contacts the Keytool service, which registers the app and generates the App ID\Key pair. Once that process is complete, the LE presents a summary of the request and the generated App ID\Key values. Note that the Key value is obfuscated – this is to ensure that it is only shared on a need-to-know basis to protect the secrecy and security of this important value. Click Back to see the list of registered apps, including the one you just created.
No approval process? No multi-day latency? No kidding?
Under the old app registration process, LMS Admins provide approval for app registration requests via an email-based approval process – even if they request the apps for themselves! The new app registration process puts app registration directly into the hands of LMS Admins, and auto-approves requests due to the trusted nature of the LMS Admin role. Now, Admins can build their own processes for taking in requests from institution staff and integration partners and instantly issue keys to them via a secure channel like an FTP site or encrypted email.
Note: The old app registration process will continue as normal until all clients transition to the new process by upgrading to the appropriate version of the LE. See the App Registration FAQs and Best Practices for more details.
Updating values on registered apps
The new app registration process also allows Admins to update metadata for Limited apps that are registered to their environment. This edit feature is especially handy if your Trusted URL changes.
Note: If you edit an app that was registered prior to August 28th, 2014 when the Trusted URL value was introduced, you’ll have the option to enter a valid Trusted URL.
From the Manage Extensibility screen, click the app name to reveal the complete app details and then click Edit. Update the values in any available field.
Note: Universal apps can only be updated by the requester via the Keytool.
Deleting registered apps
Are you ready to retire an app? Did an App ID\Key pair get leaked? You can delete any Limited apps that are registered to your environment.
Caution: Once you confirm this action, it cannot be undone. If in doubt, Disable an app until you can confirm that it should be deleted.
What do you think?
Join the discussion in the ValenceUsers forum to share your impressions of the new app registration process.
Last week, we introduced a new Keytool feature that is part of the phased roll-out of the Whitelisting feature of the Valence Authentication model.
So far, users have been able to navigate the new field and have entered Trusted URLs for app registration requests. But to make things even easier, we’ve made the Trusted URL field editable within Keytool. (Note: The original post has been updated to reflect this change.)
What does this change mean for me?
Now, when you register your app, you can put your expected Trusted URL in place or simply use a placeholder value if you’re unsure of the final endpoint for authentication of your app. So if this value changes, or you don’t know what it will be at the time you register your app, you can log back into Keytool to edit this value from the View Registered Apps screen.
As always, you can let us know what you think of this feature change in the ValenceUsers forum.