Creating Basic Scripts with the ShareFile PowerShell SDK

In my previous blog, I talked about the basics of authenticating and making requests with the ShareFile PowerShell SDK.  If you haven’t read that yet, I recommend you go back and read it first before this post.

PowerShell Control Flow

Now that you can make basic calls to the API and can retrieve data, you need to learn what you can do with that data and how multiple calls can create useful scripts for automating tasks.  If you already know PowerShell, you can skip this section, if you do not, I’ll be talking about some basic programming concepts such as functions, loops, and switch statements.

Functions

Creating a function is one of the most basic concepts in programming.  PowerShell is no different.  You can declare a function simply by using the keyword Function.

Function FindDownloadableFiles {
}

The above function does not take any parameters, but you can add them easily in 2 different ways.  Those with programming experience will recognize the first

Function FindDownloadableFiles ($sfLogin) {
}

This allows you to pass in any information you might want to the function without having to retrieve it again.  For example if I already have my $sfLogin, I don’t want to create it again, I can just pass it into the function.

The way to call this function in your script is simply

FindDownloadableFiles($sfLogin)

PowerShell also allows a second way to add parameters to a function. This second way is more useful if you are running the script from the command line.

Function FindDownloadableFilesByType {
Param ( [string]$FileType="xls")
}

In this case, I am passing a parameter of type String to decide what $FileType I want.  I am also defaulting the $FileType to “xls” if nothing is passed in.

The way to call this function is slightly different, the parameters are added to the function call much like we do with the API requests.

FindDownloadableFilesByType –FileType “xls”

Loops

Loops are also essential parts of programming, often times you retrieve large pieces of data and need to go through each piece in order to execute some other command on it.  There are a few different kinds of loops, but for today I will focus on the ForEach loop, which is often the most useful for parsing through data.

$sfItems = Send-SfRequest -Client $sfLogin -Entity Items -Expand Children
foreach($sfChildItem in $sfItems.Children){
      }

So I’m using a call I talked about in the last blog to pull all the Children items of the root folder.  Then I declare my loop to go through each of the Children items.

You’ll also notice I’m using the notation $sfItems.Children.  When you use the –Expand parameter the related objects are returned as an array of entities attached to an attribute on the primary entity.  It looks like this in raw format.  I’ve simplified this result quite a bit, for a better idea of full result attributes go to http://api.sharefile.com

{
"FileCount":2,
"Id":"fohxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"Children": [{
    "FileCount":1,
    "Info": {   “CanDownload” : True, ...    },
    "FileName":"Images",
    "Parent": {   ...  },
    "CreationDate":"2014-02-24T16:46:51.99Z",
  },
  {
    "FileCount":1,
    "Info": {   “CanDownload” : False, ...  },
    "FileName":"Images2",
    "Parent": { ... },
    "CreationDate":"2014-01-21T16:46:51.99Z",
  }],
...
}

In order to access attributes returned like this we use something called “dot notation” this means if I wanted to get the FileCount attribute from the above result set I would use

$sfItems.FileCount

Switch Statements

Let’s go back to our loop.

$sfItems = Send-SfRequest -Client $sfLogin -Entity Items -Expand Children
foreach($sfChildItem in $sfItems.Children){
       #Create an action for each ChildItem
      }

Now that we are parsing through all of our Children Items we need to check and see if these items are able to be downloaded.  We can do this with something called selection controls. If statements fall into this category, but in this example I am going to focus on the Switch statement which tends to be easier to use in PowerShell.

$sfItems = Send-SfRequest -Client $sfLogin -Entity Items -Expand Children
foreach($sfChildItem in $sfItems.Children){
      switch ($sfChildItem.Info.CanDownload ) {
            "True" {
                 Write-Host $sfChildItem.FileName + “ can be downloaded”
            }
           "False" {
                 Write-Host $sfChildItem.FileName + “ cannot be downloaded”
           }
      }

The switch is defined by using the variable you want to “switch” on in the declaration.  In our example we want to see what the value of the attribute CanDownload is for each Children Item.  We use our dot notation to say get the attribute CanDownload which exists in the Info object which is in the Children object.  In dot notation this is simply $sfChildItem.Info.CanDownload

Once we have the variable we create something called “cases” which are possible values the variable can be and if the variable matches one of these values we define actions to take.  In our example our cases are simply “True” or “False”.  If the CanDownload attribute is “True” we write out to the console that the item can be downloaded, and vice-versa for “False”.

Putting it all together

If we combine everything we just learned, this is what the script will look like:

Function FindDownloadableFiles($sfLogin) {
   $sfItems = Send-SfRequest -Client $sfLogin -Entity Items -Expand Children
    foreach($sfChildItem in $sfItems.Children){
        switch ($sfChildItem.Info.CanDownload ) {
          "True" {
                 Write-Host $sfChildItem.FileName + “ can be downloaded”
            }
           "False" {
                 Write-Host $sfChildItem.FileName + “ cannot be downloaded”
           }
        } #close switch
    } #close loop
}

$sfLogin = New-SfClient
FindDownloadableFiles($sfLogin)