Below is a post by Jeff Bentley (@redinnc on Twitter)
BlackBerry WorkDrives is a great tool for collaboration and file retrieval for the Enterprise. It is offered as a free application for BlackBerry 10 devices that are BlackBerry Balance enabled, or EMM Regulated. WorkDrives allows the user to access remote network paths (UNC) or SharePoint sites from their device.
Leveraging the “always on, always connected VPN” abilities of the BlackBerry device, the user has access to the information that they would normally access via their PC/Laptop. The network paths or SharePoint sites might contain information such as documents, files, images, etc. The key takeaway is that this information is behind the firewall, and you don’t need your PC/laptop to access it (as long as you have access to the information).
Maurice White wrote a blog post on 05/01/2014 about how to invoke WorkDrives from your application. You can reference that Blog on how to include WorkDrives access into your application by leveraging the Invocation Framework within BlackBerry 10.
As a user of WorkDrives myself, I have been somewhat frustrated that I have to remember all my network drives, personal mapped drives, and SharePoint sites whenever I update my BlackBerry device’s OS version (I get to do that often being an employee and Beta testing releases). Since I don’t do a good job of using BlackBerry Link to backup my data, I rely on memory and my love of reconfiguring applications.
While this may be a bad example of why someone would want to automate the creation of drive/site entries in WorkDrives, think about wanting to populate those drives/sites for your users that have had WorkDrives installed on their devices. You might have information that all users need to reference or have access to, and rather than have all of your users manually configuring their WorkDrives application (let alone remember all the locations they might need or want). Maybe you’d like to have all their mapped drives (you know, the ones that get mapped when they login) on their device (that are unique to each user). Wouldn’t it be great to do this for your users in a proactive fashion?
Well, it is very easy to do, and you don’t need a lot of coding skills to accomplish this. The delivery mechanism will use the BlackBerry Push capabilities that are built into the BlackBerry devices and BlackBerry Enterprise Service 10 (BES 10). The Push request can be accomplished with any development language that can issue HTTP Post commands.
BES 10 supports PAP (Push Access Protocol – industry standard) or RIM Push. This Blog will speak to RIM push as it is easier to use and potentially less stressful on your BES 10 servers.
First, I’ll give you a link for documentation of the WorkDrives administration: WorkDrives Admin Guide
Next, there are 2 basic things you need to have or know before you can get started, content format and who is to receive it. We’ll focus on the content first since that what you want to send. The “payload” needs to be in a JSON (JavaScript Object Notation) format, and this is really just a set of key value pairs for presenting information to receiving applications. Much like XML, it is a standard and readily used in the HTML world as the preferred format.
To find more information about the payload parameters use this link.
Simple one request sample payload:
{
"Command":"ChangeMappings",
"Content":
[
{
"Action":"CREATE",
"UniqueName":"Test drive",
"Type":"NetworkDrive",
"Uri":"//servername/foldername"
}
]
}
Multiple request sample payload:
{
"Command":"ChangeMappings",
"Content":
[
{
"Action":"CREATE",
"UniqueName":"Test drive",
"Type":"NetworkDrive",
"Uri":"//servername/foldername"
},
{
"Action":"CREATE",
"UniqueName":"Test drive #2",
"Type":"NetworkDrive",
"Uri":"//servername/anotherfoldername"
}
]
}
The braces are used for starting and ending entries, and the brackets are for elements. The indenting is only for easier reading. You can learn more about JSON by clicking on the link above. You only need to understand the Content section since every payload delivered to WorkDrives requires these 4 key value pairs:
- Action – CREATE, CREATEREPLACE, DELETE
- UniqueName – Name that will appear on the entry in WorkDrives
- Type – NetworkDrive or Sharepoint
- Uri – destination in the format befitting of the Type property
This information can be in a simple text file (.txt) or can be dynamically generated in your code. This content will be sent via the HTTP Post request as the data.
So, at this point you have your content, and hopefully you know who you want to send it to. You’re probably thinking of ways to dynamically build the Uri for each person’s needs, or figure out what they would want as a drive entry, but now you need to just figure out how to deliver this payload. Unfortunately you can’t send it in an email, or as a BBM message. You need to use the BlackBerry Push capabilities of the device and BES. Here is a good page referencing RIM Push.
For this Push to work, we need some piece of code that can make an HTTP Post call to the BES to deliver your payload. As mentioned above, you can use any scripting language (PowerShell, PHP, or even good old VBScript), compiled languages (C#, VB .NET, etc.). Since I’m old school (really old school), I’ll show you an example in VBScript that is 58 lines of code (all error handling included). If your PC/Laptop is running any version of Windows, you can simply copy this text into a text file and rename the file extension to “.vbs”. There are just 4 lines of code (highlighted in red) that you need to change to reflect your environment:
BES Server – DNS entry of the BES that the recipient is located on
BES Port – Default is 8080 but your installation might have changed this (referred to as Push Port)
Recipient – Email address or PIN of person to receive the payload
Data File – File that contains the JSON formatted payload
VBScript Sample
Set fso = CreateObject("Scripting.FileSystemObject") 'Initialize file object
Set objShell = CreateObject("WScript.Shell") 'Create windows scripting object
sCurrentFolder = objShell.CurrentDirectory 'Get folder name where script is executing
sFailureReason = "" 'Initialize variable
'********************************************************************
'Define values to variables that are required for execution
'********************************************************************
'Specify the DNS entry for your BES server and port number to send the data through
sBESServer = "dnsservername"
sBESPort = "8080"
'Specify the email address of the recipient to receive the contents of this push request
sRecipient = "emailaddress"
'Define the application details
'Port/ID unique to all implementations of WorkDrives
sApplicationPort = "sys.cfs.enterprise.gYABgJMjNCifxklxri87rZD71hA"
sApplicationDataFile = sCurrentFolder & "/filename.txt"
If fso.FileExists(sApplicationDataFile) = False Then 'Does the source application data file exist?
sFailureReason = "Unable to locate Application data file"
Else
'Get application data in the format required to receive it on the device
Set objFile = fso.OpenTextFile(sApplicationDataFile, 1)
sFileContents = objFile.ReadAll
objFile.Close
Set WinHttpReq = WScript.CreateObject("WinHttp.WinHttpRequest.5.1") 'Create HTTP object
'Build headers
sMDSServerURL = "http://" & sBESServer & ":" & sBESPort 'Build BES MDS Address
WinHttpReq.Open "POST", sMDSServerURL & "/push?DESTINATION=" & sRecipient & "&PORT=" & sApplicationPort & "&REQUESTURI=/", False
WinHttpReq.SetRequestHeader "Content-Type", "text/plain" 'Set content type
WinHttpReq.Send sFileContents 'Send request to BES MDS-CS server with data
Select Case WinHttpReq.Status 'Analyze the status code for the post
Case 200
'It worked, nothing to do here
Case 400
sFailureReason = "General error (" & WinHttpReq.StatusText & ")"
Case 403
sFailureReason = "Email address '" & sRecipient & "' not found"
Case 404
sFailureReason = "Request not received by MDS-CS (" & WinHttpReq.StatusText & ")"
Case 503
sFailureReason = "MDS-CS busy"
Case Else
sFailureReason = "Invalid server or port (" & WinHttpReq.StatusText & ")"
End Select
End If
If sFailureReason "" Then 'Did the data push work?
MsgBox "Unable to push data to BlackBerry device:" & vbCRLF & Space(4) & sFailureReason, vbOKOnly + vbCritical,"DataPush Failure"
Else
Msgbox "Data successfully received by MDS server",vbOKOnly, "DataPush Completion"
End If
Now that you have your content, recipient, and delivery mechanism configured, you are good to go. Simply execute your script (double click on the .vbs file from Windows Explorer) and observe the results (an alert that is displayed at the end containing success or error message). If the Push was successfully received by the BES (correct BES Server and recipient), the payload will be delivered to the device as quick as the BES can make contact with the device. BES will store the information until it connects with the device – up to 24 hours is usually the default. You can override this setting with a specific header (see link above to RIM Push page).
You will likely also notice that a notification will appear in the BlackBerry Hub telling the user that a network drive was added to BlackBerry Work Drives by your administrator and that you have to provide login credentials.
Since the BES doesn’t analyze or care what is in the payload, you need to ensure it is properly formatted for acceptance by the WorkDrives application. If it is wrongly formatted, WorkDrives will not display any message to the user, it will simply ignore the request. It will appear as though it was never sent. There is an optional header for acknowledgement of receipt (see Push link again), but it means you have to write a server side component to receive those notifications. I would highly recommend this type of closure/confirmation once you want to put things into production, as I’m sure you don’t want to just send data and hope for delivery.
Now that you have successfully sent a payload to WorkDrives and see that the new drive is listed, you’re probably thinking about how you can take this to the next level. Confirmations, personal drive mappings, document repositories, etc. You have just leveraged one of the 4 Pillars of Enterprise Development using the strength that the BlackBerry platform provides. You can use this Push capability in any application that you write for BlackBerry. Deliver the content before it is needed, and remove the need for an application to poll for changes or updates.
If you have any questions, please leave a comment below.
